int error = hw_SetDisplayAdapter(hwPluginBase *self, ULONG flags,
                struct hwTagList *tags);

HWSDAFLAGS_PERMANENT:

If this flag is set, the display adapter will be made permanent. This means that other plugins won't be able to overwrite this display adapter with their own one. If HWSDAFLAGS_PERMANENT is set, all subsequent calls to hw_SetDisplayAdapter() will fail and your display adapter will persist.

HWSDAFLAGS_TIEDVIDEOBITMAP:

Set this flag to indicate that your video bitmaps depend on your display, i.e. they cannot exist without the display. This is normally true for all device-dependent bitmaps. If this flag is set and the user closes the display, Hollywood will call your ReadVideoPixels() function to convert the device-dependent bitmaps (DDBs) into device-independent bitmaps (DIBs). Once the user opens the display again, Hollywood will call your AllocVideoBitMap() function to convert the DIBs back into DDBs. Obviously, this flag is only meaningful if you also set the HWSDAFLAGS_VIDEOBITMAPADAPTER flag.

HWSDAFLAGS_SOFTWAREFALLBACK:

Set this flag if you want your display adapter to fall back to software bitmaps if hardware bitmaps (i.e. video bitmaps) cannot be allocated for some reason, e.g. out of memory. If this flag is set and Hollywood cannot allocate a hardware bitmap, it will simply allocate a software bitmap instead. Obviously, this flag is only meaningful if you also set the HWSDAFLAGS_VIDEOBITMAPADAPTER flag.

HWSDAFLAGS_CUSTOMSCALING:

Set this flag to indicate that your display adapter wants to do scaling on its own in case autoscaling mode is active. If this flag is not set, Hollywood will do the autoscaling for you but this might be slower then. See BltBitMap for details.

HWSDAFLAGS_VIDEOBITMAPADAPTER:

Set this flag to indicate that your display adapter supports custom hardware (video) bitmaps. Hollywood will then call your AllocVideoBitMap() function whenever it needs to allocate a hardware bitmap. See AllocVideoBitMap for details. If you set this flag, you should also provide the HWSDATAG_VIDEOBITMAPCAPS tag to fine-tune the capabilities of your video bitmap adapter (see below).

HWSDAFLAGS_BITMAPADAPTER:

Set this flag to indicate that your display adapter wants to allocate all software bitmaps on its own. Hollywood will then call your AllocBitMap() function whenever it needs to allocate a software bitmap. Hollywood's inbuilt software bitmap handler will never be used if this flag is set. See AllocBitMap for details.

HWSDAFLAGS_DOUBLEBUFFERADAPTER:

Set this flag if your display adapter wants to offer a custom hardware double buffering mode. If this flag is set, Hollywood will call your plugin's BeginDoubleBuffer() function when the user calls Hollywood's BeginDoubleBuffer() function with the optional argument set to True. See BeginDoubleBuffer for details.

HWSDAFLAGS_ALPHADRAW:

Set this flag to indicate that your implementations of RectFill(), Line(), and WritePixel() support alpha-blending. If this flag isn't set, Hollywood will do any alpha-blending on its own and your implementations of functions like RectFill() will only have to be able to draw static colors. See RectFill for details.

HWSDAFLAGS_SLEEP:

Set this flag to indicate that you want Hollywood to call your plugin's Sleep() function whenever it needs to sleep for a certain amount of time. See Sleep for details.

HWSDAFLAGS_VWAIT:

Set this flag to indicate that you want Hollywood to call your plugin's VWait() function whenever it needs to wait for the vertical blank. See VWait for details.

HWSDAFLAGS_MONITORINFO:

Set this flag to indicate that your display adapter provides its own functions to query information about all available monitors. If this flag is set, Hollywood will call your plugin's GetMonitorInfo() function to obtain information about monitors available to the system. See GetMonitorInfo for details.

HWSDAFLAGS_GRABSCREEN:

Set this flag to indicate that your plugin provides custom routines for grabbing the desktop screen pixels. If this flag is set, Hollywood will call your plugin's GrabScreenPixels() function whenever it needs to grab the desktop screen's pixels. If this flag isn't set, Hollywood will use its inbuilt screen grabber. See GrabScreenPixels for details.

HWSDAFLAGS_DRAWALWAYS:

By default, Hollywood will never call any of your display adapter's functions that draw graphics to a display when that display is hidden or minimized. If you don't want this behaviour, set this flag and Hollywood will always call your display adapter's drawing functions, even when the display is hidden or minimized. (V6.1)

HWSDAFLAGS_PALETTE:

Set this flag to tell Hollywood that your display adapter can handle CLUT graphics. If HWSDAFLAGS_PALETTE is set, display adapters need to be prepared to deal with the new HWBBFLAGS_SRCCLUTBITMAP flag in BltBitMap(). If this flag is set, the bitmap passed to BltBitMap() is a CLUT one and you need to draw it using the palette and transparent pen passed in the new Palette and TransPen fields of struct hwBltBitMapCtrl. See BltBitMap for details. (V9.0)

HWSDAFLAGS_PENDRAW:

Set this flag to indicate that your Line(), RectFill(), and WritePixel() implementations can handle pen values instead of colors as well. In that case, the color argument of those functions will be set to a pen index instead but only if the display that is passed to the functions is a display that has set HWDISPTAG_PALETTEMODE to True in its OpenDisplay() instantiation. (V9.0)

HWSDAFLAGS_SETPALETTE:

Set this flag to indicate that your display adapter can change pixel colors by changing the palette. This is very useful on classic Amiga hardware where you can simply modify the hardware's color registers to change pixels without actually copying any pixel data. If display adapters set this flag, Hollywood will call into the display adapter's SetPalette() function whenever the palette changes instead of re-drawing all pixels with the new palette by calling your BltBitMap() function. To make your display adapter support the new SetPalette() function, you also need to set the HWEXT_DISPLAYADAPTER_PALETTE extension bit in your plugin. Note that HWSDAFLAGS_SETPALETTE is only supported for displays that have set HWDISPTAG_PALETTEMODE to True their OpenDisplay() instantiation. (V9.0)

HWSDAFLAGS_CLUTBITMAPADAPTER:

Set this flag to indicate that your display adapter can also allocate CLUT bitmaps. Hollywood will then call your AllocBitMap() function whenever it needs to allocate a CLUT bitmap. Hollywood's inbuilt CLUT bitmap handler will never be used if this flag is set. See AllocBitMap for details. Note that HWSDAFLAGS_BITMAPADAPTER needs to be set as well if you set this flag. HWSDAFLAGS_CLUTBITMAPADAPTER can't be used without setting HWSDAFLAGS_BITMAPADAPTER. (V9.0)

HWSDAFLAGS_MENUADAPTER:

Set this flag to indicate that your display adapter supports menus. Hollywood will then pass menus that should be attached to your display in the HWDISPTAG_MENU tag when calling OpenDisplay() or by calling your SetMenuBar() function. Note that if you set this flag, you also need to set the HWEXT_DISPLAYADAPTER_MENUADAPTER extension bit in your plugin and implement all functions required for menu handling. (V9.0)

HWSDAFLAGS_SETTRAYICON:

Set this flag to indicate that your display adapter supports custom tray icons. Hollywood will then call your SetTrayIcon() implementation whenever the script changes the tray icon. Note that if you set this flag, you also need to set the HWEXT_DISPLAYADAPTER_TRAYICON extension bit in your plugin. (V9.0)

Additionally, hw_SetDisplayAdapter() accepts a tag list that allows you to configure further settings for the new display adapter. The following tags are currently recognized:

HWSDATAG_PIXELFORMAT:

This tag allows you to set the pixel format that should be used when allocating bitmaps. Hollywood will allocate all of its software bitmaps in the pixel format specified in the iData member of this tag. See Pixel format information for a list of available pixel formats. Please note that this tag doesn't have any effect if you provide your own bitmap adapter by setting the HWSDAFLAGS_BITMAPADAPTER. Obviously, the pixel format specified here doesn't have any effect on hardware (video) bitmaps either.

HWSDATAG_BITMAPHOOK:

This tag can be used to provide custom routines for drawing to software bitmaps. You have to set the iData member of this tag to a combination of the following flags:

HWBMAHOOK_BLTBITMAP:

Indicates that your BltBitMap() implementation wants to be called whenever Hollywood needs to blit a bitmap that doesn't have an accompanying mask or alpha channel to a software bitmap. Your BltBitMap() implementation has to do this blit operation then instead of Hollywood. See BltBitMap for details. Hollywood will pass the HWBBFLAGS_DESTBITMAP flag to BltBitMap() so that it knows that the specified destination handle is a software bitmap.

HWBMAHOOK_BLTMASKBITMAP:

Indicates that your BltBitMap() implementation wants to be called whenever Hollywood needs to blit a bitmap that has an accompanying mask to a software bitmap. Your BltBitMap() implementation has to do this blit operation then instead of Hollywood. See BltBitMap for details. Hollywood will pass the HWBBFLAGS_DESTBITMAP flag to BltBitMap() so that it knows that the specified destination handle is a software bitmap.

HWBMAHOOK_BLTALPHABITMAP:

Indicates that your BltBitMap() implementation wants to be called whenever Hollywood needs to blit a bitmap that has an an accompanying alpha channel to a software bitmap. Your BltBitMap() implementation has to do this blit operation then instead of Hollywood. See BltBitMap for details. Hollywood will pass the HWBBFLAGS_DESTBITMAP flag to BltBitMap() so that it knows that the specified destination handle is a software bitmap.

HWBMAHOOK_BLTCLUTBITMAP:

Indicates that your BltBitMap() implementation wants to be called whenever Hollywood needs to blit a CLUT bitmap to an RGB software bitmap. Your BltBitMap() implementation has to do this blit operation then instead of Hollywood. See BltBitMap for details. Hollywood will pass the HWBBFLAGS_DESTBITMAP flag to BltBitMap() so that it knows that the specified destination handle is a software bitmap. Note that HWBMAHOOK_BLTCLUTBITMAP is only supported if HWSDAFLAGS_PALETTE is set as well. (V9.0)

HWBMAHOOK_RECTFILL:

Indicates that your RectFill() implementation wants to be called whenever Hollywood needs draw a filled rectangle to a software bitmap. Your RectFill() implementation has to do this operation then instead of Hollywood. See RectFill for details. Hollywood will pass the HWRFFLAGS_DESTBITMAP flag to RectFill() so that it knows that the specified destination handle is a software bitmap.

HWBMAHOOK_WRITEPIXEL:

Indicates that your WritePixel() implementation wants to be called whenever Hollywood needs plot a single pixel to a software bitmap. Your WritePixel() implementation has to do this operation then instead of Hollywood. See WritePixel for details. Hollywood will pass the HWWPFLAGS_DESTBITMAP flag to WritePixel() so that it knows that the specified destination handle is a software bitmap.

HWBMAHOOK_LINE:

Indicates that your Line() implementation wants to be called whenever Hollywood needs draw a line to a software bitmap. Your Line() implementation has to do this operation then instead of Hollywood. See Line for details. Hollywood will pass the HWLIFLAGS_DESTBITMAP flag to Line() so that it knows that the specified destination handle is a software bitmap.

HWSDATAG_VIDEOBITMAPCAPS:

If you've enabled video bitmap support for this display adapter by setting the HWSDAFLAGS_VIDEOBITMAPADAPTER flag, the iData member of this tag configures the exact capability set of your video bitmap adapter. This must be set to a combination of the following flags:

HWVBMCAPS_SCALE:

Set this to indicate that your video bitmap adapter supports bitmap scaling. See AllocVideoBitMap for details.

HWVBMCAPS_TRANSFORM:

Set this to indicate that your video bitmap adapter supports bitmap transformation. See AllocVideoBitMap for details.

HWVBMCAPS_OFFSCREENCOLOR:

Set this to indicate that your BltBitMap(), RectFill(), Line(), and WritePixel() functions can draw to off-screen video bitmaps in color mode. Hollywood will pass one of the HWxxFLAGS_DESTVIDEOBITMAP flags to these functions to indicate that the destination is a video bitmap.

HWVBMCAPS_OFFSCREENALPHA:

Set this to indicate that your BltBitMap(), RectFill(), Line(), and WritePixel() functions can draw to the alpha channel of off-screen video bitmaps. Hollywood will pass the HWxxFLAGS_DESTVIDEOBITMAP and the HWxxFLAGS_ALPHAONLY flags to these functions to indicate that the destination is a video bitmap and that the function must only draw to the alpha channel.

HWVBMCAPS_BLITTRANSFORM:

Set this to indicate that your BltBitMap() implementation is able to do its own bitmap transformation based on the Matrix member that is set in struct hwBltBitMapCtrl. If you don't set this tag, Hollywood will do the transformation for you but this might be slower than a customized implementation in BltBitMap(). (V8.0)

HWVBMCAPS_BLITALPHAMOD:

Set this to indicate that your BltBitMap() implementation is able to do its own alpha modulation based on the AlphaMod member that is set in struct hwBltBitMapCtrl. If you don't set this tag, Hollywood will do the alpha modulation for you but this might be slower than a customized implementation in BltBitMap(). (V8.0)

See Display adapter plugins for information on how to write display adapter plugins.

self

hwPluginBase pointer passed to InitPlugin()

flags

combination of flags (see above)

tags

tag list specifying further options (see above)

error

error code or 0 for success