HGE::Texture_Lock

Locks a texture for direct access.

DWORD *Texture_Lock(
  HTEXTURE texture,
  bool bReadOnly = true,
  int left = 0,
  int top = 0,
  int width = 0,
  int height = 0
);

Parameters

texture

Handle of a texture to lock.

bReadOnly

Optional. If true, the texture will not be updated after unlocking.

left

Optional X-coordinate of the top-left corner of the texture region to lock.

top

Optional Y-coordinate of the top-left corner of the texture region to lock.

width

Optional width of the texture region to lock.

height

Optional height of the texture region to lock.

Return value

If successful, returns a pointer to the locked texture data. Otherwise returns 0.

Remarks

The locked texture data is an array of DWORD color values. Only 32-bit textures are lockable, so textures can't be locked on some very old video cards like Intel Solano. Render target and compressed textures are also not lockable.

If the texture region was specified, the returned pointer is appropriately offset from the start of the texture data. To access a texture pixel within the specified region use the following syntax:

DWORD color = locked_ptr[y*tex_width+x];

Where tex_width is the texture width, which you could obtain with Texture_GetWidth.

If you're not going to modify the texture and just want to read some pixels - always set bReadOnly to true, this will skip updating texture in video memory, thus will work faster. Also if you're modifying just a part of the texture, always specify the region. Only this region will be updated in video memory.

When finished accessing the texture you must unlock it with Texture_Unlock call.

Requirements

Header: hge.h
Import library: hge.lib

See also

Texture_Unlock