void BltBitMap(APTR bmap, APTR handle, struct hwBltBitMapCtrl *ctrl,
         ULONG flags, struct hwTagList *tags);

In parameter 3, Hollywood will pass a struct hwBltBitMapCtrl which looks like this:

struct hwBltBitMapCtrl { int SrcX; // [in] int SrcY; // [in] int DstX; // [in] int DstY; // [in] int Width; // [in] int Height; // [in] int ScaleWidth; // [in] int ScaleHeight; // [in] ULONG ScaleMode; // [in] APTR Mask; // [in] APTR Alpha; // [in] struct hwMatrix2D *Matrix; // [in, V8.0] double AnchorX; // [in, V8.0] double AnchorY; // [in, V8.0] int AlphaMod; // [in, V8.0] ULONG *Palette; // [in, V9.0] ULONG TransPen: // [in, V9.0] };

Here's a description of the individual structure members:

SrcX:

Contains the x position in the source bitmap that marks the start offset for the copy operation. This is relative to the upper-left corner of the source bitmap.

SrcY:

Contains the y position in the source bitmap that marks the start offset for the copy operation. This is relative to the upper-left corner of the source bitmap.

DstX:

Contains the destination x position relative to the upper-left corner.

DstY:

Contains the destination y position relative to the upper-left corner.

Width:

Contains the number of columns to copy.

Height:

Contains the number of rows to copy.

ScaleWidth:

If you've passed the HWSDAFLAGS_CUSTOMSCALING flag in your call to hw_SetDisplayAdapter() then this will contain the desired scale width when autoscaling mode is active. If you haven't passed HWSDAFLAGS_CUSTOMSCALING, Hollywood will take care of scaling automatically and this member will always be zero.

ScaleHeight:

If you've passed the HWSDAFLAGS_CUSTOMSCALING flag in your call to hw_SetDisplayAdapter() then this will contain the desired scale height when autoscaling mode is active. If you haven't passed HWSDAFLAGS_CUSTOMSCALING, Hollywood will take care of scaling automatically and this member will always be zero.

ScaleMode:

If you've passed the HWSDAFLAGS_CUSTOMSCALING flag in your call to hw_SetDisplayAdapter() then this will contain the desired scale mode when autoscaling mode is active. This can be either 0 for brute force scaling or 1 for interpolated scaling using pixel antialiasing.

Mask:

Contains a pointer to mask bitmap or NULL if there is no mask. This member is only used when drawing software bitmaps to video bitmaps or hardware double buffers.

Alpha:

Contains a pointer to an alpha channel bitmap or NULL if there is no alpha channel. This member is only used when drawing software bitmaps to video bitmaps or hardware double buffers.

Matrix:

If you've set the HWVBMCAPS_BLITTRANSFORM capability in HWSDATAG_VIDEOBITMAPCAPS, this may be set to a struct hwMatrix2D which means that your implementation has to apply the specified transformation matrix when blitting. Your transformed blit operation also has to take the anchor points that are passed in AnchorX and AnchorY into account (see below). Note that if Matrix is non-NULL, all coordinates passed to your BltBitMap() implementation are non-clipped. They will be set to the raw coordinates passed to Hollywood's DisplayBrush() function. This is different to the case where Matrix is NULL. In that case, all coordinates are clipped to the current display's boundaries. (V8.0)

AnchorX:

If the Matrix member is non-NULL, this will be set to the horizontal anchor point of the transformation. This will always be between 0 and 1. See Matrix for details. You only need to handle AnchorX if you have set the HWVBMCAPS_BLITTRANSFORM capability bit. (V8.0)

AnchorY:

If the Matrix member is non-NULL, this will be set to the vertical anchor point of the transformation. This will always be between 0 and 1. See Matrix for details. You only need to handle AnchorY if you have set the HWVBMCAPS_BLITTRANSFORM capability bit. (V8.0)

AlphaMod:

If you've set the HWVBMCAPS_BLITALPHAMOD capability in HWSDATAG_VIDEOBITMAPCAPS, this may be set to an alpha value that should be multiplied into the blitting operation. Your BltBitMap() implementation has to modulate all pixels by this alpha value when blitting. If you haven't set HWVBMCAPS_BLITALPHAMOD, you can ignore this structure member. (V8.0)

Palette:

If HWBBFLAGS_SRCCLUTBITMAP is set (see below), this field will contain the palette for the CLUT bitmap passed to BltBitMap(). The palette pens will be stored as normal RGB colors in Palette. Note that HWBBFLAGS_SRCCLUTBITMAP can only ever be set if you have passed HWSDAFLAGS_PALETTE in your hw_SetDisplayAdapter() call. (V9.0)

TransPen:

If HWBBFLAGS_SRCCLUTBITMAP is set (see below), this field can be set to a pen that shouldn't be drawn by your BltBitMap() implementation. Note that the TransPen field will normally be HWPEN_NONE. It can only ever be set to a transparent pen in case your plugin supports custom double buffers. Also, HWBBFLAGS_SRCCLUTBITMAP can only ever be set if you have passed HWSDAFLAGS_PALETTE in your hw_SetDisplayAdapter() call. (V9.0)

The way BltBitMap() should operate is defined by the flags parameter. The following flags are currently recognized:

HWBBFLAGS_SRCVIDEOBITMAP:

The source bitmap passed in parameter 1 is a video bitmap allocated by AllocVideoBitMap(). If this flag isn't set, then the source bitmap will be a software bitmap that has either been allocated by Hollywood or by your plugin (if you've set the HWSDAFLAGS_BITMAPADAPTER flag). Note that video bitmaps can only be drawn to a hardware double buffer allocated by your plugin or to another offscreen video bitmap. Thus, if HWBBFLAGS_SRCVIDEOBITMAP is set you can be certain that Hollywood is either currently in hardware double buffer mode, i.e. it has previously called your plugin's BeginDoubleBuffer() function, or that the HWBBFLAGS_DESTVIDEOBITMAP flag is set.

HWBBFLAGS_DESTVIDEOBITMAP:

The destination handle passed in parameter 2 is a video bitmap allocated by AllocVideoBitMap(). This can only happen if you've set the HWVBMCAPS_OFFSCREENCOLOR or HWVBMCAPS_OFFSCREENALPHA capabilities in HWSDATAG_VIDEOBITMAPCAPS to enable offscreen rendering to video bitmaps. Otherwise, HWBBFLAGS_DESTVIDEOBITMAP will never be set.

HWBBFLAGS_DESTALPHAONLY:

This is only set in connection with HWBBFLAGS_DESTVIDEOBITMAP. If Hollywood wants you to draw to the alpha channel of your video bitmap allocated by AllocVideoBitMap(), it will indicate this by setting HWBBFLAGS_DESTALPHAONLY. If HWBBFLAGS_DESTVIDEOBITMAP is set and HWBBFLAGS_DESTALPHAONLY isn't, you have to draw to the color channels of the video bitmap instead. Note that HWBBFLAGS_DESTALPHAONLY will only ever be set if you've set the HWVBMCAPS_OFFSCREENALPHA capability flag in HWSDATAG_VIDEOBITMAPCAPS to enable offscreen rendering to video bitmap alphachannels.

HWBBFLAGS_DESTBITMAP:

The destination handle passed in parameter 2 is a software bitmap allocated by Hollywood or your plugin's AllocBitMap() function if you've set the HWSDAFLAGS_BITMAPADAPTER in your call to hw_SetDisplayAdapter(). Note that HWBBFLAGS_DESTBITMAP will only ever be set if you've passed either HWBMAHOOK_BLTBITMAP, HWBMAHOOK_BLTMASKBITMAP, HWBMAHOOK_BLTALPHAHOOK or HWBMAHOOK_BLTCLUTHOOK in HWSDAFLAGS_BITMAPHOOK. Otherwise, Hollywood will do the rendering to the software bitmap on its own and you don't have to care. HWBBFLAGS_DESTBITMAP will only ever be set if you've explicitly requested that you want to do offscreen drawing to software bitmaps on your own by setting the appropriate bitmap hook flags.

HWBBFLAGS_DONOTBLEND:

This flag indicates that BltBitMap() should not do any alpha blending. Instead, it should just do a raw copy of the color and alpha channel pixel data without any blending. This may only ever be set if the source or destination bitmap is a video bitmap allocated by your plugin, i.e. HWBBFLAGS_DONOTBLEND may only be set if HWBBFLAGS_DESTVIDEOBITMAP or HWBBFLAGS_SRCVIDEOBITMAP is defined, too. It will never be set when dealing with software bitmaps.

HWBBFLAGS_IGNOREBKBUFFER:

If autoscaling is active and HWSDAFLAGS_CUSTOMSCALING hasn't been set in your call to hw_SetDisplayAdapter() this flag may be set to indicate that the source bitmap doesn't match the dimensions of your back buffer. Thus, if this flag is set you must not draw into the back buffer first. Instead, you must draw directly to your display. If HWBBFLAGS_IGNOREBKBUFFER is set, the destination handle will always be a display handle allocated by OpenDisplay(). Since HWBBFLAGS_IGNOREBKBUFFER is only used when Hollywood is in autoscale mode, it will always refresh the whole display, i.e. SrcX, SrcY, DstX, and DstY will all be 0 and Width and Height will correspond to the display's dimensions.

HWBBFLAGS_SRCCLUTBITMAP:

If you have set HWSDAFLAGS_PALETTE in your call to hw_SetDisplayAdapter(), Hollywood will set this flag whenever it has passed a CLUT bitmap to you. You then need to draw the CLUT bitmap using the palette and transparent pen passed in the Palette and TransPen fields of struct hwBltBitMapCtrl (see above). (V9.0)

This may all sound quite complicated but in fact, the complexity of the BltBitMap() function can be greatly reduced if your plugin doesn't support offscreen drawing and video bitmaps. In that case, all your BltBitMap() implementation has to do is to grab the pixels from the source bitmap and draw them to the destination display. You won't have to support the Mask and Alpha members of the struct hwBltBitMapCtrl in that case either, because they will only ever be set if BltBitMap() is used to draw a software bitmap to a video bitmap or a hardware double buffer.

To get the raw pixels of Hollywood bitmaps, you can use the hw_LockBitMap() function. If you've installed your own bitmap and video bitmap adapters, you can also directly interpret the handle pointers that are passed to this function because you've allocated them. It's not necessary to use hw_LockBitMap() on bitmaps that have been allocated by your plugin.

A typical implementation of BltBitMap() should do the following whenever it has to draw directly to the display: It should first draw the pixels into a back buffer (unless HWBBFLAGS_IGNOREBKBUFFER is set or a hardware double buffer is used) and then it should draw the pixels from this back buffer to the display.

This function doesn't have to do any clipping. Hollywood will perform clipping itself before calling BltBitMap().

If your plugin supports hardware double buffering and Hollywood has put your display into hardware double buffering mode by calling your plugin's BeginDoubleBuffer() function, this function must not draw anything to the display but only to the back buffer. Hollywood will call your plugin's Flip() function when it wants you to draw the back buffer to the display.

You might want to use the hw_RawBltBitMap() function in your implementation to copy the pixels of bitmaps stored as raw pixel buffers. See hw_RawBltBitMap for details.

bmap

source bitmap

handle

destination display or bitmap (depends on the flags that are set, see above)

ctrl

pointer to a struct hwBltBitMapCtrl containing parameters for the blit

flags

flags specifying how to copy the pixels (see above)

tags

additional options (currently always NULL)