Partager via

LockSurface method

  • Article

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

Syntax

HRESULT retVal = object.LockSurface(pBounds, ulTimeOut, dwFlags, riid, ppPointer, pulGenerationId);

Parameters

  • pBounds [in]
    Type: const DXBNDS

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

  • ulTimeOut [in]
    Type: unsigned long

    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 does not return until the lock is acquired.

  • dwFlags [in]
    Type: DWORD

    DWORD that indicates 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]
    Type: REFIID

    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]
    Type: void

    Address of a pointer to the returned interface.

  • pulGenerationId [out]
    Type: unsigned long

    Pointer to the generation ID associated with the surface.

Remarks

Use this method before accessing a DXSurface to obtain a pointer to a read-only or read/write interface. Typically, this method returns 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 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 returns the generation ID of the surface when the lock was obtained.

Any number of threads can use IDXSurface::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 regions to be released. If the regions 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 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 does not generate new run information for the surface.

Even if you use neither of these flags, the IDXARGBReadPtr::MoveAndGetRunInfo method returns 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 DXLOCKF_NONPREMULT flag to indicate the type of data that is being sent to the surface. This can be especially useful for procedural surfaces, which can 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 Release method on the returned interface.

See also

DXLOCKSURF