Microsoft DirectX 9.0 SDK Update (October 2004)

Texture.LockRectangle Method

Language:

Note: This documentation is preliminary and is subject to change.

Locks a rectangle on a texture resource.

Definition

Visual Basic .NET Public Function LockRectangle( _
    ByVal level As Integer, _
    ByVal rect As Rectangle, _
    ByVal flags As LockFlags, _
    ByRef pitch As Integer _
) As GraphicsStream
C# public GraphicsStream LockRectangle(
    int level,
    Rectangle rect,
    LockFlags flags,
    out int pitch
);
Managed C++ public: GraphicsStream* LockRectangle(
    int level,
    Rectangle rect,
    LockFlags flags,
    int *pitch
);
JScript .NET public function LockRectangle(
    level : int,
    rect : Rectangle,
    flags : LockFlags,
    pitch : int
) : GraphicsStream;

Parameters

level System.Int32. A level of the texture resource to lock.
rect System.Drawing.Rectangle. A Rectangle Leave Site to lock. To expand the dirty region to cover the entire texture, omit this parameter.
flags Microsoft.DirectX.Direct3D.LockFlags. Zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are Discard, NoDirtyUpdate, NoSystemLock, and ReadOnly. For a description of the flags, see LockFlags.
pitch System.Int32. Pitch of the returning data.

Return Value

Microsoft.DirectX.GraphicsStream . A GraphicsStream object that describes the locked region.

Remarks

Textures created with Pool.Default are not lockable. Textures created in video memory are lockable when created with Usage.Dynamic. For more information about usages, see Usage.

For performance reasons, dirty regions are recorded only for level 0 of a texture. Dirty regions are automatically recorded when Texture.LockRectangle is called without Lock.NoDirtyUpdate or Lock.ReadOnly. For more information, see Device.UpdateTexture.

The only lockable format for a depth stencil texture is Format.D16Lockable.

Video memory textures cannot be locked, but must be modified by calling Device.UpdateSurface or Device.UpdateTexture. There are exceptions for some proprietary driver pixel formats that Microsoft® DirectX® 9.0 does not recognize. These can be locked.

See Also


© 2004 Microsoft Corporation. All rights reserved. Terms of use.

Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center