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


Handle of a texture to lock.
Optional. If true, the texture will not be updated after unlocking.
Optional X-coordinate of the top-left corner of the texture region to lock.
Optional Y-coordinate of the top-left corner of the texture region to lock.
Optional width of the texture region to lock.
Optional height of the texture region to lock.

Return value

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


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.


Header: hge.h
Import library: hge.lib

See also