DDLOCKOUT structure (ddkmapi.h)
The DDLOCKOUT structure contains a description of the surface.
Syntax
typedef struct _DDLOCKOUT {
DWORD ddRVal;
DWORD dwSurfHeight;
DWORD dwSurfWidth;
LONG lSurfPitch;
PVOID lpSurface;
DWORD SurfaceCaps;
DWORD dwFormatFlags;
DWORD dwFormatFourCC;
DWORD dwFormatBitCount;
union {
DWORD dwRBitMask;
DWORD dwYBitMask;
};
union {
DWORD dwGBitMask;
DWORD dwUBitMask;
};
union {
DWORD dwBBitMask;
DWORD dwVBitMask;
};
} DDLOCKOUT, *LPDDLOCKOUT;
Members
ddRVal
Specifies the location in which Microsoft DirectDraw writes the return value of the DxApi function for DD_DXAPI_LOCK operations. A return code of DD_OK indicates success.
dwSurfHeight
dwSurfWidth
Specify the dimensions of the surface, in pixels.
lSurfPitch
Specifies the distance, in bytes, to the start of the next line.
lpSurface
Points to the surface memory.
SurfaceCaps
Indicates a set of flags that specify the capabilities of the surface. This member can be set to one or more of the following flags:
| Flag | Meaning |
|---|---|
| DDSCAPS_3DDEVICE | This surface can be used for 3D rendering. Applications can use this flag to ensure that a device that can only render to a certain heap has offscreen surfaces allocated from the correct heap. If this flag is set for a heap, the surface is not allocated from that heap. |
| DDSCAPS_ALLOCONLOAD | Memory for the surface is not allocated until the surface is loaded by the application using the IDirect3DDevice7::Load method. |
| DDSCAPS_ALPHA | This surface contains alpha information. The pixel format must be queried to determine whether this surface contains only alpha information or alpha information interlaced with pixel color data (such as RGBA or YUVA). |
| DDSCAPS_BACKBUFFER | This surface is the back buffer of a surface flipping structure. Typically, this capability is set by the application's CreateSurface method when the DDSCAPS_FLIP flag is used. Only the surface that immediately precedes the DDSCAPS_FRONTBUFFER surface has this capability set. The other surfaces are identified as back buffers by the presence of the DDSCAPS_FLIP flag, their attachment order, and the absence of the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities. If this capability is sent to the application's CreateSurface method, a stand-alone back buffer is being created. After this method is called, this surface could be attached to a front buffer, another back buffer, or both to form a flipping surface structure. For more information, see the AddAttachedSurface method in the DirectX SDK documentation. DirectDraw supports an arbitrary number of surfaces in a flipping structure. |
| DDSCAPS_COMPLEX | A complex surface is being described. A complex surface results in the creation of more than one surface. The additional surfaces are attached to the root surface. The complex structure can be destroyed only by destroying the root. |
| DDSCAPS_FLIP | This surface is a part of a surface flipping structure. When this capability is passed to the application's CreateSurface method, a front buffer and one or more back buffers are created. DirectDraw sets the DDSCAPS_FRONTBUFFER bit on the front-buffer surface and the DDSCAPS_BACKBUFFER bit on the surface adjacent to the front-buffer surface. The dwBackBufferCount member of the DDSURFACEDESC structure must be set to at least 1 in order for the method call to succeed. The DDSCAPS_COMPLEX capability must always be set when creating multiple surfaces by using the CreateSurface method. |
| DDSCAPS_FRONTBUFFER | This surface is the front buffer of a surface flipping structure. This flag is typically set by the application's CreateSurface method when the DDSCAPS_FLIP capability is set. If this capability is sent to the CreateSurface method, a stand-alone front buffer is created. This surface will not have the DDSCAPS_FLIP capability. It can be attached to other back buffers to form a flipping structure by using the application's AddAttachedSurface method. |
| DDSCAPS_HWCODEC | This surface should be able to have a stream decompressed to it by the hardware. |
| DDSCAPS_LIVEVIDEO | This surface should be able to receive live video. |
| DDSCAPS_LOCALVIDMEM | This surface exists in true, local display memory rather than nonlocal display memory. If this flag is specified then DDSCAPS_VIDEOMEMORY must be specified as well. This flag cannot be used with the DDSCAPS_NONLOCALVIDMEM flag. |
| DDSCAPS_MIPMAP | This surface is one level of a mipmap. This surface will be attached to other DDSCAPS_MIPMAP surfaces to form the mipmap. This can be done explicitly by creating a number of surfaces and attaching them by using the application's AddAttachedSurface method, or implicitly by the application's CreateSurface method. If this capability is set, DDSCAPS_TEXTURE must also be set. |
| DDSCAPS_MODEX | This surface is a 320x200 or 320x240 Mode X surface. |
| DDSCAPS_NONLOCALVIDMEM | This surface exists in nonlocal display memory rather than true, local display memory. If this flag is specified, then DDSCAPS_VIDEOMEMORY flag must be specified as well. This cannot be used with the DDSCAPS_LOCALVIDMEM flag. |
| DDSCAPS_OFFSCREENPLAIN | This surface is any offscreen surface that is not an overlay, texture, z-buffer, front-buffer, back-buffer, or alpha surface. It is used to identify plain surfaces. |
| DDSCAPS_OPTIMIZED | Not currently implemented. |
| DDSCAPS_OVERLAY | This surface is an overlay. It may or may not be directly visible depending on whether it is currently being overlaid onto the primary surface. DDSCAPS_VISIBLE can be used to determine if it is being overlaid at the moment. |
| DDSCAPS_OWNDC | This surface will have a device context (DC) association for a long period. |
| DDSCAPS_PALETTE | This device driver allows unique DirectDrawPalette objects to be created and attached to this surface. |
| DDSCAPS_PRIMARYSURFACE | The surface is the primary surface. It represents what is visible to the user at the moment. |
| DDSCAPS_PRIMARYSURFACELEFT | This surface is the primary surface for the left eye. It represents what is visible to the user's left eye at the moment. When this surface is created, the surface with the DDSCAPS_PRIMARYSURFACE capability represents what is seen by the user's right eye. |
| DDSCAPS_STANDARDVGAMODE | This surface is a standard VGA mode surface, and not a ModeX surface. This flag cannot be used in combination with the DDSCAPS_MODEX flag. |
| DDSCAPS_SYSTEMMEMORY | This surface memory was allocated in system memory. |
| DDSCAPS_TEXTURE | This surface can be used as a 3D texture. It does not indicate whether the surface is being used for that purpose. |
| DDSCAPS_VIDEOMEMORY | This surface exists in display memory. |
| DDSCAPS_VIDEOPORT | This surface can receive data from a hardware video port. |
| DDSCAPS_VISIBLE | Changes made to this surface are immediately visible. It is always set for the primary surface, as well as for overlays while they are being overlaid and texture maps while they are being textured. |
| DDSCAPS_WRITEONLY | Only write access is permitted to the surface. Read access from the surface may generate a general protection fault (GPF), but the read results from this surface are not meaningful. |
| DDSCAPS_ZBUFFER | This surface is the z-buffer. The z-buffer contains information that cannot be displayed. Instead, it contains bit-depth information that is used to determine which pixels are visible and which are obscured. |
dwFormatFlags
Specifies a set of optional control flags. This member can be set to a combination of the following flags:
| Flag | Meaning |
|---|---|
| DDPF_ALPHA | The pixel format describes an alpha-only surface. |
| DDPF_ALPHAPIXELS | The surface has alpha channel information in the pixel format. |
| DDPF_ALPHAPREMULT | Reserved for system use. |
| DDPF_BUMPDUDV | Bump map dUdV data in the pixel format is valid. |
| DDPF_BUMPLUMINANCE | Luminance data in pixel format is valid. This flag is used when hanging luminance off bumpmap surfaces; the bitmask for the luminance portion of the pixel is then indicated by the dwBumpLuminanceBitCount member of the DDPIXELFORMAT structure. |
| DDPF_COMPRESSED | The surface accepts pixel data in the specified format and compresses it during the write operation. |
| DDPF_FOURCC | The FOURCC code is valid. |
| DDPF_LUMINANCE | Luminance data in the pixel format is valid. This flag is used for luminance only or luminance plus alpha surfaces; the bit depth is then indicated by the dwLuminanceBitCount member of the DDPIXELFORMAT structure. |
| DDPF_PALETTEINDEXED1 | The surface is 1-bit color indexed. |
| DDPF_PALETTEINDEXED2 | The surface is 2-bit color indexed. |
| DDPF_PALETTEINDEXED4 | The surface is 4-bit color indexed. |
| DDPF_PALETTEINDEXED8 | The surface is 8-bit color indexed. |
| DDPF_PALETTEINDEXEDTO8 | The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette. |
| DDPF_RGB | The RGB data in the pixel format structure is valid. |
| DDPF_RGBTOYUV | The surface accepts RGB data and translates it during the write operation to YUV data. The format of the data to be written is contained in the pixel format structure. The DDPF_RGB flag is set. |
| DDPF_STENCILBUFFER | The surface contains stencil information along with the Z information. |
| DDPF_YUV | The YUV data in the pixel format structure is valid. |
| DDPF_ZBUFFER | The pixel format describes a z-buffer-only surface. |
| DDPF_ZPIXELS | The surface is in RGBZ format. |
dwFormatFourCC
Specifies the FOURCC code. For more information about FOURCC codes, see the DirectX SDK documentation.
dwFormatBitCount
Specifies the number of bits per pixel (4, 8, 16, 24, or 32) of the RGB or YUV data.
dwRBitMask
Specifies the mask for red bits.
dwYBitMask
Specifies the mask for Y bits.
dwGBitMask
Specifies the mask for green bits.
dwUBitMask
Specifies the mask for U bits.
dwBBitMask
Specifies the mask for blue bits.
dwVBitMask
Specifies the mask for V bits.
Requirements
| Requirement | Value |
|---|---|
| Header | ddkmapi.h (include Ddkmapi.h) |