APTR handle = AllocVideoBitMap(int width, int height, ULONG flags,
                  struct hwTagList *tags);

Hollywood will pass a taglist which contains further parameters for the operation to AllocVideoBitMap(). Your implementation must be able to deal with the following tags:

HWAVBMTAG_DATA:

The pData member of this tag item will be set to an object that should be used to initialize the video bitmap's pixels. This tag will always be provided because there is no way to set the video bitmap's pixel data at a later stage. That is why the pixel data for the video bitmap is already provided by Hollywood at allocation time. If the HWAVBMFLAGS_BITMAPDATA flag is set, then pData will contain a handle to another video bitmap. This means that the new video bitmap should copy all pixels from this video bitmap handle. It is guaranteed that the video bitmap handle provided here matches the size of the new video bitmap that is to be allocated. If HWAVBMFLAGS_BITMAPDATA is not set, then pData contains a pointer to a 32-bit ARGB pixel array that contains the raw pixels that should be used to initialize the new video bitmap. This 32-bit ARGB array will always be of the size width * height * 4. No row padding is applied to this buffer.

HWAVBMTAG_SRCWIDTH:

If this tag is set and the HWAVBMTAG_MATRIX2D tag is not passed, then the width value passed in parameter 1 is to be interpreted as a scaled value while the width passed in this tag's iData member contains the width of the source pixel data that is passed in HWAVBMTAG_DATA. This means that your implementation has to scale the source pixel data provided in HWAVBMTAG_DATA to the dimensions passed in parameters 1 and 2. It also has to take the scale mode into account that is passed in HWAVBMTAG_SCALEMODE. Hollywood uses this tag to offer hardware-accelerated scaling of video bitmaps. Please note that HWAVBMTAG_SRCWIDTH will only ever be passed to AllocVideoBitMap() if your plugin has explicitly declared that it supports video bitmap scaling by setting the HWVBMCAPS_SCALE flag in HWSDATAG_VIDEOBITMAPCAPS. If HWAVMTAG_SRCWIDTH and HWAVBMTAG_MATRIX2D are both passed, then you have to apply a transformation matrix to the source pixel data. See the documentation of HWAVBMTAG_MATRIX2D below for more information.

HWAVBMTAG_SRCHEIGHT:

This is the height counterpart for HWAVBMTAG_SRCWIDTH. See above for a description on what this tag is used for.

HWAVBMTAG_SCALEMODE:

If HWAVBM_SRCWIDTH and HWAVBM_SRCHEIGHT or HWAVBM_MATRIX2D are set, this tag will also be provided to tell you about the scale mode that Hollywood wants you to use. Currently, only 0 and 1 are supported here. A value of 0 in iData means that you should do hard scaling without any interpolation whereas a value of 1 means that Hollywood wants you to do use anti-alias interpolation. See above in the description of HWAVBM_SRCWIDTH for more information.

HWAVBMTAG_MATRIX2D:

If this tag is set, then Hollywood wants you to apply a transformation to the source pixel data provided in HWAVBMTAG_DATA and store the transformation's resulting pixels in the new video bitmap that is to be allocated. Hollywood has already calculated the dimensions for the new video bitmap and passed them to this function in parameters 1 and 2. To get to know about the dimensions of the source pixel data, you have to examine the tags HWAVBMTAG_SRCWIDTH and HWAVBM_SRCHEIGHT which are always passed if HWAVBMTAG_MATRIX2D is set. The pData member of this tag item will be set to a pointer to a struct hwMatrix2D that contains all parameters for the transformation. Note that your implementation also has to take the scale mode that is passed in HWAVBMTAG_SCALEMODE into account. Hollywood uses this tag to offer hardware-accelerated transformation of video bitmaps. Please note that HWAVBMTAG_MATRIX2D will only ever be passed to AllocVideoBitMap() if your plugin has explicitly declared that it supports video bitmap transformation by setting the HWVBMCAPS_TRANSFORM flag in HWSDATAG_VIDEOBITMAPCAPS.

HWAVBMTAG_DISPLAY:

If you've set the HWSDAFLAGS_TIEDVIDEOBITMAP flag when installing your display adapter using hw_SetDisplayAdapter() then this tag will always be provided and its pData member will be set to a handle to the display that this video bitmap should be allocated for. This will always be a handle returned by your OpenDisplay() implementation.

In addition to the taglist items described above, Hollywood can also set the following flags and your plugin has to be prepared to handle them:

HWAVBMFLAGS_BLEND:

If this flag is set, then the data provided in HWAVBMTAG_DATA contains alpha channel transparency information and your plugin is expected to do the alpha blending with this data whenever it draws this bitmap. Note that the alpha channel data is always non-premultiplied.

HWAVBMFLAGS_BITMAPDATA:

If this flag is set, then the data provided in HWAVBMTAG_DATA is a handle to another video bitmap which Hollywood wants you to use as the pixel data source. If this flag isn't set, then HWAVBMTAG_DATA contains a pointer to a 32-bit ARGB pixel array. See the documentation of HWAVBMTAG_DATA above for more information.

HWAVBMFLAGS_SMOOTH:

If the SmoothScale tag has been set to True in Hollywood's @BRUSH, LoadBrush(), CreateBrush(), or CopyBrush() commands, this flag will be set. (V8.0)

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

width

desired bitmap width in pixels

height

desired bitmap height in pixels

flags

allocation flags (see above)

tags

taglist containing additional parameters (see above)

handle

handle to the bitmap or NULL in case of an error