APTR lock = LockBitMap(APTR handle, ULONG flags, struct
                hwos_LockBitMapStruct *bmlock, struct hwTagList *tags);

struct hwos_LockBitMapStruct { APTR Data; // [out] int Modulo; // [out] int PixelFormat; // [out] int BytesPerPixel; // [out] int Width; // [out] int Height; // [out] };

Your LockBitMap() implementation has to write the following information to the individual structure members:

Data:

Must be set to a pointer to the bitmap's actual pixel data. The pointer must be valid until Hollywood calls UnLockBitMap() on the handle that is returned by this function.

Modulo:

Must be set to the bitmap's modulo width, i.e. the length of a single row of pixels. For bitmaps of type HWBMTYPE_RGB this value must be specified in pixels. For the other bitmap types, this value must be specified in bytes.

PixelFormat:

This must be set to the pixel format used by the raw pixel array that you've set in Data. See Pixel format information for details.

BytesPerPixel:

This must be set to how many bytes are needed for a single pixel. Note that for CLUT bitmaps this must always be 1, even if the actual bit depth is less than 8 bits.

Width:

Must be set to the bitmap's width.

Height:

Must be set to the bitmap's height.

Hollywood will also pass a combination of flags to this function. The following flags are currently supported:

HWLBMFLAGS_READONLY:

If this flag is set, Hollywood will only need read access to the bitmap. It won't write to the pixel array you return in the Data member of the struct hwos_LockBitMapStruct.

LockBitMap() has to return a lock handle for this bitmap. This is an opaque datatype only known by your plugin. It's only used to unlock the bitmap again when Hollywood is finished with it. Hollywood will call UnLockBitMap() then, passing the handle which was returned by LockBitMap(). If this function fails to lock the bitmap, return NULL.

This function will usually be called very often by Hollywood so your implementation should be efficient and should not have to copy the pixels to a new memory block first. Instead, it should be designed in a way that allows immediate access to the pixel data.

LockBitMap() is an optional API and must only be implemented if HWSDAFLAGS_BITMAPADAPTER has been passed to hw_SetDisplayAdapter(). See hw_SetDisplayAdapter for details.

handle

bitmap handle allocated by AllocBitMap()

flags

flags for the lock operation (see above)

bmlock

pointer to a struct hwos_LockBitMapStruct to be filled out by this function

tags

reserved for future use (currently NULL)

lock

bitmap lock or NULL in case there was an error