DarkBASIC Professional Help File

DX11 LOCK IMAGE

Locks a copy of the specified image data for reading and writing.
The old image data will be retained until DX11 UNLOCK IMAGE is called.
Multiple images may be locked at once. Take note that this is rather low level functionality and unlike the Pixelmap functionality, all
you will be provided with is a pointer to the raw image data (for now anyway, this may change in future releases). It is up to you to verify its format and size and access it appropriately.
Any pixel formats and texture arrays / cubemaps are supported for locking however, but only a single array index and / or mip map level may be locked for the same image at once.
Take note that smaller images may be padded to occupy a larger block of memory; for example a 4x4 pixel image may be stored in a 16x16 pixel block - this is up to the GPU to decide
and may differ from one machine, or even invocation on the same machine, to another. You can use DX11 GET IMAGE PIXEL BUFFER WIDTH and DX11 GET IMAGE PIXEL BUFFER HEIGHT to
find out the actual dimensions of the allocated image block. Likewise, DX11 GET IMAGE PIXEL BUFFER SIZE returns the full size of the image block, including any padding.

Syntax

    Return Boolean = DX11 LOCK IMAGE(img, [arrayId], [mipLevel], [offsetX], [offsetY], [width], [height])

Parameters

    img

> Dword
> The image to lock.

    [Optional] arrayId

> Dword
> If the specified image is a texture array or a cubemap / cubemap array you can use this parameter to indicate which image within the array to lock. Only one per array texture at a time!

    [Optional] mipLevel

> Dword
> You can specify what mip level to lock here. Mip zero is the highest (full) resolution image.

    [Optional] offsetX

> Dword
> The first pixel along the x-axis to lock. You can optionally use this to lock only a subset of an image's pixel data. Defaults to 0 for the first, leftmost pixel. Must be specified if offsetY/width/height is.

    [Optional] offsetY

> Dword
> The first pixel along the x-axis to lock. You can optionally use this to lock only a subset of an image's pixel data. Defaults to 0 for the first, leftmost pixel. Must be specified if offsetX/width/height is.

    [Optional] width

> Dword
> The width, in pixels, of the image sub-area to lock. Set to zero (0) to lock the entire width of the image. Must be specified if height is.

    [Optional] height

> Dword
> The height, in pixels, of the image sub-area to lock. Set to zero (0) to lock the entire height of the image. Must be specified if width is.

Returns

True if the image wasn't previously locked, or false if it was. If re-locked the image is first unlocked and then locked again to ensure all previous data is updated, which may be inefficient.

See also

IMAGE Functions Menu
DX11 Function Categories