Creating Cubic-Environment Map Surfaces

You create a cubic environment map by calling the IDirectDraw7::CreateSurface method in C++ or DirectDraw7.CreateSurface in Visual Basic. Cube maps are complex surfaces; that is, they are a set of attached surfaces, created by DirectDraw in a single call. Surfaces that were created individually cannot be attached to each other to create a cubic-environment map. Cubic-environment map textures must be square, with dimensions that are a powers-of-two.

[C++]

The following code shows how your C++ application might create a simple cubic-environment map.

// For this example, the pDD variable is a valid pointer 
// to an IDirectDraw7 interface.
DDSURFACEDESC2 ddsd;

ZeroMemory((LPVOID)&ddsd, sizeof(DDSURFACEDESC2));

ddsd.dwSize         = sizeof(DDSURFACEDESC2);
ddsd.dwFlags        = DDSD_CAPS | DDSD_WIDTH | 
                      DDSD_HEIGHT | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE;

// Set the pixel format to a valid texture format here.

// Dimensions are an arbitrary, but must be a power-of-two.
ddsd.dwWidth  = 64;  
ddsd.dwHeight = 64; 

// Set caps for a system memory cube-map texture that is a valid 
// render-target surface.
ddsd.ddsCaps.dwCaps  = DDSCAPS_COMPLEX | DDSCAPS_3DDEVICE | 
                       DDSCAPS_TEXTURE;
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP|DDSCAPS2_CUBEMAP_ALLFACES;

LPDIRECTDRAWSURFACE7 pddsCubeMap;

// Create the cube map.
if( FAILED( pDD->CreateSurface( &ddsd, pddsCubeMap, NULL ) ) )
{
    // code to handle error goes here.
}

Note If you intend to render into the faces of a cube map, the surface description you provide when you create the surface must contain the DDSCAPS_3DDEVICE capability.

Cube maps can be managed textures. If you include either the DDSCAPS2_TEXTUREMANAGE or DDSCAPS2_TEXTUREMANAGE capability flag in the surface capabilities when you create the surface, the resulting texture will be managed. For more information, see Automatic Texture Management.

[Visual Basic]

The following Visual Basic code shows how your application might create a simple cubic-environment map.

' For this example, the dd variable is a valid reference
' to a DirectDraw7 object.
On Local Error Resume Next

Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_WIDTH Or _
              DDSD_HEIGHT Or DDSD_PIXELFORMAT
             
ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE

' Set the pixel format to a valid texture format here.

' Dimensions are an arbitrary, but must be a power-of-two.
ddsd.dwWidth = 64: ddsd.dwHeight = 64

' Set caps for a system memory cube-map texture that is a valid
' render-target surface.
ddsd.ddsCaps.dwCaps = DDSCAPS_COMPLEX Or DDSCAPS_3DDEVICE Or _
                      DDSCAPS_TEXTURE
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP Or DDSCAPS2_CUBEMAP_ALLFACES

Dim ddsCubeMap As DirectDrawSurface7

' Create the cube map.
Set ddsCubeMap = dd.CreateSurface(ddsd)

If Err.Number <> DD_OK Then
    ' code to handle error goes here.
End If

Note If you intend to render into the faces of a cube map, the surface description you provide when you create the surface must contain the DDSCAPS_3DDEVICE capability.