IDXSurface Interface

The IDXSurface interface is used to access DXSurface objects, which store images. The interface is supported by objects that wrap traditional bitmap memory arrays, as well as objects that produce images procedurally. DXSurface objects are created through the IDXSurfaceFactory interface. Other objects, such as procedural surfaces, can implement the IDXSurface interface to act as image objects.

The basic bitmap object is exposed by DXSurface objects, which have a class identifier (CLSID) of CLSID_DXSurface. These DXSurfaces wrap DirectDrawSurface objects or can be used to perform operations directly on memory buffers.

This interface provides methods for determining information about surfaces, such as the native pixel format and bounds. The IDXSurface interface also is used to lock the surface to provide access to the samples or to a handle to a device context.

Implement this interface when you are creating a custom surface. You must reimplement this interface to support new pixel formats that are introduced. If you want to introduce a new pixel format, you need to implement the DXSurface object with the support for the new pixel format. For a list of currently supported pixel formats, see Supported Pixel Formats.

Other objects can implement the IDXSurface to act as an image object. Objects of this type are typically referred to as procedural surfaces because they produce data on request. Two examples of procedural surfaces are gradient fills and Surface Modifiers.

This interface inherits from the IDXBaseObject interface.

IDXSurface Methods

GetAppData Retrieves an application-specific DWORD of data.

GetBounds Retrieves a structure containing the surface's boundary region.

GetColorKey Retrieves the surface's color key value.

GetDirectDrawSurface Retrieves an interface on the underlying DirectDrawSurface object if the DXSurface object is aggregated onto a DirectDrawSurface.

GetPixelFormat Retrieves the pixel format of the surface.

GetStatusFlags Retrieves the status flags of the DXSurface object.

LockSurface Locks a region of the surface and returns a pointer through which you can access samples on DXSurfaces.

LockSurfaceDC Locks a region of the surface and returns an IDXDCLock interface.

SetAppData Sets the surface's application-specified DWORD of data.

SetColorKey Sets the surface's color key value.

SetStatusFlags Sets the status flags of the DXSurface object.

IDXSurface::GetAppData

IDXSurface Interface

Retrieves an application-specific DWORD of data.

Syntax

HRESULT GetAppData(
    DWORD *pdwAppData
);

Parameters

pdwAppData
[out] Pointer to a DWORD of data that was previously set with the SetAppData method. If no call has been made to SetAppData, the value returned will be zero.

Return Value

Returns S_OK for success or E_POINTER to indicate a NULL pointer argument; these are the only valid return values. The call will not fail if a valid pointer is given.

Remarks

This method retrieves a "tag" set by an application for a DXSurface. For example, applications that use 3-D transforms can use this method to retrieve a tag from a transform input surface. This would enable the application to identify which textures were hit when doing 3-D hit testing. However, applications can use this data in any way that is useful.
The IDXSurfaceFactory::CreateD3DRMTexture method will copy the application data to the texture from the DXSurface when it creates the texture.
All surface implementations must support SetAppData and GetAppData.

See Also

IDXSurface::SetAppData

IDXSurface::GetBounds

IDXSurface Interface

Retrieves a structure containing the surface's boundary region.

Syntax

HRESULT GetBounds(
    DXBNDS *pBounds
);

Parameters

pBounds
[out] Pointer to the DXBNDS boundary structure containing the surface's bounding region.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IDXSurfaceModifier::SetBounds

IDXSurface::GetColorKey

IDXSurface Interface

Retrieves the surface's color key value.

Syntax

HRESULT GetColorKey(
    DXSAMPLE *pColorKey
);

Parameters

pColorKey
[out] Pointer to the DXSAMPLE structure that indicates the color to be treated as transparent.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Some surface implementations will not allow color keys, so the method can return E_NOTIMPL.

See Also

IDXSurface::SetColorKey

IDXSurface::GetDirectDrawSurface

IDXSurface Interface

Retrieves an interface on the underlying DirectDrawSurface object if the DXSurface object is aggregated onto a DirectDrawSurface.

Syntax

HRESULT GetDirectDrawSurface(
    REFIID riid,
    void **ppSurface
);

Parameters

riid
[in] Value indicating the type of interface to return. This can be any interface ID defined by DirectDraw, such as IID_IDirectDrawSurface, IID_IDirectDrawSurface2, or IID_IDirectDrawSurface3, as exposed by the underlying DirectDraw driver.

ppSurface
[out] Address of a pointer to the surface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method will return E_NOTIMPL if the DXSurface does not have an underlying DirectDrawSurface. This is the case for some surfaces, such as procedural surfaces.

IDXSurface::GetPixelFormat

IDXSurface Interface

Retrieves the pixel format of the surface.

Syntax

HRESULT GetPixelFormat(
    GUID *pFormatID,
    DXSAMPLEFORMATENUM *pSampleFormatEnum
);

Parameters

pFormatID
[out] Pointer to the pixel format's globally unique identifier (GUID).

pSampleFormatEnum
[out] Pointer to one of the DirectX Transform-supported pixel formats from the DXSAMPLEFORMATENUM enumeration.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Either pointer can be NULL if you do not want the information. Transform writers who override this method must check for NULL pointers in both parameters.

See Also

DXSAMPLEFORMATENUM, Supported Pixel Formats

IDXSurface::GetStatusFlags

IDXSurface Interface

Retrieves the status flags of the DXSurface object.

Syntax

HRESULT GetStatusFlags(
    DWORD *pdwStatusFlags
);

Parameters

pdwStatusFlags
[out] Pointer to the surface status flags.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The returned DWORD value contains flags from the DXLOCKSURF and DXSURFSTATUS enumerations.
This method returns the DXSURF_TRANSIENT flag if the data in the surface changes often. If it does, the user should not cache information about the surface. Run information will never be generated for transient surfaces.
If the DXSURF_READONLY flag is set, you cannot obtain an IDXARGBReadWritePtr interface to the surface.

See Also

IDXSurface::SetStatusFlags, DXSURFSTATUS, DXLOCKSURF

IDXSurface::LockSurface

IDXSurface Interface

Locks a region of the surface and returns a pointer through which you can access samples on DXSurfaces.

Syntax

HRESULT LockSurface(
    const DXBNDS *pBounds,
    ULONG ulTimeOut,
    DWORD dwFlags,
    REFIID riid,
    void **ppPointer,
    ULONG *pulGenerationId
);

Parameters

pBounds
[in] Pointer to the region to lock, as specified by the DXBNDS structure; specifying NULL locks the whole surface.

ulTimeOut
[in] Time, in milliseconds, that the caller will wait for the lock to be obtained. If the lock attempt fails, E_ABORT is returned. If INFINITE is specified, the method will not return until the lock is acquired.
dwFlags
[in] DWORD value indicating the lock type, specified by the DXLOCKSURF enumeration. Specify DXLOCKF_READ (or 0) for read-only access, or DXLOCKF_READWRITE for read/write access to the surface.

riid
[in] Interface to return for accessing the samples of the surface. The format for passing this parameter for C programs is &IID_ , and for C++ it is IID_ .

ppPointer
[out] Address of a pointer to the returned interface.

pulGenerationId
[out] Pointer to the generation ID associated with the surface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method before accessing a DXSurface to obtain a pointer to a read-only or read/write interface. Typically, this method will return the IDXSurfaceModifier, IDXARGBReadPtr, or IDXARGBReadWritePtr interface. These interfaces enable transforms to access the surface samples and to alter the stored image.
The z-axis and t-axis values of the DXBNDS structure will usually range from 0 to 1 for two-dimensional surfaces. If the surface is procedural, the z and t values might not be used, depending on the implementation of the interface.
The pulGenerationId parameter is optional. If it is used, it will return the generation ID of the surface when the lock was obtained.
Any number of threads can use LockSurface to obtain read pointers to the same surface or regions within that surface. When requesting a read/write pointer, however, the method checks to see whether the requested bounds overlap any regions that are currently read/write locked. If there is no overlap, the method locks the specified region of the surface and returns the read/write pointer. If the regions do overlap, the method waits ulTimeOut milliseconds for the conflicting region(s) to be released. If the region(s) not are released before the timeout, an E_ABORT HRESULT is returned.
This approach to surface locking allows multiple threads to modify different regions of the same surface. It is very important for a thread to stay within the bounds it has specified for operations on a region. To make surface access as fast as possible, the code does not check that you are writing only inside your locked region. Should you write beyond your stated bounds, you might overwrite image data in other regions of the surface or corrupt your application memory.
When requesting a pointer to a region away from the origin, the method returns a pointer to that region and translates the origin to the upper-left corner of the region. All region access should be done relative to the new origin. For example, assume you lock a region from (150,200) to (250,300). All access to that region with the returned pointer should happen within the region (0,0) and (100,100).
The dwFlags parameter is used to specify what type of access is desired (read-only or read/write), and to provide information to the surface about what type of data access is likely to take place. Two flags, DXLOCKF_WANTRUNINFO and DXLOCKF_EXISTINGINFOONLY, control the generation of run information that is provided through the IDXARGBReadPtr::MoveAndGetRunInfo method. If you plan to use run information, you must specify DXLOCKF_WANTRUNINFO when locking the surface, to force the surface to generate run information. The process of generating run information is relatively expensive, but for static surfaces it only needs to be done once and can significantly improve the performance of some algorithms that access a surface repeatedly. If combined with DXLOCKF_EXISTINGINFOONLY, the method will not generate new run information for the surface.
Even if you use neither of these flags, the IDXARGBReadPtr::MoveAndGetRunInfo method will return valid run information. However, it is possible that the method will return a value of DXRUNTYPE_UNKNOWN for the run type that is then the full width of the locked region. Run information is never generated for transient surfaces.
If you plan to access samples that are not alpha-premultiplied, you should set the flag DXLOCKF_NONPREMULT to give the surface a hint about the type of data access it can expect. This can be especially useful for procedural surfaces, which can often produce data of either type. In any case, you can access either sample type regardless of whether you set this flag.
The surface is unlocked by calling the IUnknown::Release method on the returned interface.

See Also

DXLOCKSURF

IDXSurface::LockSurfaceDC

IDXSurface Interface

Locks a region of the surface and returns an IDXDCLock interface.

Syntax

HRESULT LockSurfaceDC(
    const DXBNDS *pBounds,
    ULONG ulTimeOut,
    DWORD dwFlags,
    IDXDCLock **ppDCLock
);

Parameters

pBounds
[in] Pointer to the region to lock, as specified by the DXBNDS structure. If NULL, the entire surface will be locked.

ulTimeOut
[in] Time, in milliseconds, to wait for the lock to be obtained. You can use INFINITE for this parameter. If the lock fails because of a time-out, the call will return E_ABORT.
dwFlags
[in] DWORD value indicating the lock type. Specify DXLOCKF_READ for read-only access or DXLOCKF_READWRITE for read/write access to the surface.

ppDCLock
[out] Address of a pointer to the IDXDCLock interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is similar to the LockSurface but is used to gain access to the surface's handle to a device context (HDC) so that Microsoft® Win32® Graphics Device Interface (GDI) operations can be performed on the data. Many surfaces, such as procedural surfaces, will not have an associated HDC, so this call might return E_NOTIMPL. In this case, if an HDC is required, you might want to use the IDXSurfaceFactory::CopySurfaceToNewFormat method to obtain a DXSurface that supports an HDC.
The locking semantics are similar to LockSurface, and subregions of the surface can be locked for reading or writing. One important difference is that all HDC locks are not relative to the locked region. In addition, the HDC will reference the entire surface, regardless of the bounds locked.
The returned interface supports only a single method: IDXDCLock::GetDC, which returns an HDC. The HDC returned is valid for the entire time that a reference is held on the IDXDCLock object. When the object is released by means of IUnknown::Release, then the HDC will be released and the caller should not use it again.

IDXSurface::SetAppData

IDXSurface Interface

Sets the surface's application-specified DWORD of data.

Syntax

HRESULT SetAppData(
    DWORD dwAppData
);

Parameters

dwAppData
[in] Any DWORD value to be used by the application to store information specific to the surface.

Return Value

Returns S_OK.

Remarks

This method enables an application to "tag" a surface with a unique DWORD of data. For example, applications that use 3-D transforms can use this method to tag input surfaces to the transforms. This would enable the application to identify which textures were hit when doing 3-D hit testing. However, applications can use this data in any way that is useful.
The IDXSurfaceFactory::CreateD3DRMTexture method will copy the application data to the texture from the DXSurface when it creates the texture.
All surface implementations must support SetAppData and GetAppData.
See Also

IDXSurface::GetAppData

IDXSurface::SetColorKey

IDXSurface Interface

Sets the surface's color key value.

Syntax

HRESULT SetColorKey(
    DXSAMPLE ColorKey
);

Parameters

ColorKey
[in] A color in DXSAMPLE format indicating the color to be treated as transparent.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
Many surfaces do not support color keys, so this call could return an HRESULT of E_NOTIMPL.

Remarks

The specified color must have an alpha value of 255 (0xFF). The other color components must specify the color as a 24-bit RGB value. The surface implementation can convert this to a different color representation internally, if necessary.

See Also

IDXSurface::GetColorKey

IDXSurface::SetStatusFlags

IDXSurface Interface

Sets the status flags of the DXSurface object.

Syntax

HRESULT SetStatusFlags(
    DWORD dwStatusFlags
);

Parameters

dwStatusFlags
[in] Value to set for the surface status flags.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The value of the dwStatusFlags parameter sets flags that are defined in the DXSURFSTATUS enumeration. Specify a value of DXSURF_TRANSIENT if the data in the surface changes often. If this flag is set, the code will not generate a sample runmap when the surface is locked. Use of this flag will decrease the time required to lock a surface, at the expense of code optimization that uses the sample runmap.
To prevent write access to a surface, set the DXSURF_READONLY flag.

See Also

IDXSurface::GetStatusFlags, DXSURFSTATUS

GetAppData	Retrieves an application-specific DWORD of data.
GetBounds	Retrieves a structure containing the surface's boundary region.
GetColorKey	Retrieves the surface's color key value.
GetDirectDrawSurface	Retrieves an interface on the underlying DirectDrawSurface object if the DXSurface object is aggregated onto a DirectDrawSurface.
GetPixelFormat	Retrieves the pixel format of the surface.
GetStatusFlags	Retrieves the status flags of the DXSurface object.
LockSurface	Locks a region of the surface and returns a pointer through which you can access samples on DXSurfaces.
LockSurfaceDC	Locks a region of the surface and returns an IDXDCLock interface.
SetAppData	Sets the surface's application-specified DWORD of data.
SetColorKey	Sets the surface's color key value.
SetStatusFlags	Sets the status flags of the DXSurface object.