10.1 Overview

Plugins that have the capability flag HWPLUG_CAPS_DISPLAYADAPTER set can replace Hollywood's inbuilt display handler with a custom display handler. This is a very powerful feature and allows you to reroute Hollywood's complete graphics output and event handler through an entirely different toolkit or display driver, thus making it possible to use Hollywood scripts in completely new environments.

Optionally, display adapters can also choose to override Hollywood's inbuilt bitmap handler with custom implementations and it is also possible to offer support for custom hardware bitmaps and double buffers from display adapters. This allows you to take full advantage of device dependent bitmaps for optimized drawing.

If you're just starting out with display adapters, it is advised that you begin with a pretty basic display adapter first and then you may choose to add support for advanced features later. Functions like BltBitMap() can get quite complex if your display adapter supports all the advanced functionality that Hollywood makes available, so it might be a better idea to first implement a barebones display adapter that doesn't support video bitmaps or hardware double buffers but just reroutes all of Hollywood's graphics through a custom device. You can then use this implementation as a basis to add support for more advanced features.

Also, be sure to benchmark raw performance of scripts with your display adapter and compare them to the performance of Hollywood's inbuilt display handler to see if your adapter needs optimizing. See HandleEvents for details.

Please note that display adapters are not automatically initialized when Hollywood loads the plugin. Instead, you have to manually call hw_SetDisplayAdapter() in your RequirePlugin() function to activate the display adapter. The display adapter will then only be activated if the user calls @REQUIRE on your plugin. Otherwise, Hollywood will use its default display handler. See Auto and manual plugin initialization for details.

You don't have to implement all functions offered by the display adapter API. Many functions are optional and only have to be implemented if you explicitly request their use in your call to hw_SetDisplayAdapter(). However, it is mandatory that all functions defined by the display adapter API are declared so that Hollywood can import their symbols when it loads the plugin. Functions that are optional and that you don't enable via hw_SetDisplayAdapter() can just be dummies then. Here is an overview of all display adapter APIs that are optional:

Sleep()

Only used if activated by setting HWSDAFLAGS_SLEEP.

VWait()

Only used if activated by setting HWSDAFLAGS_VWAIT.

GetMonitorInfo()

Only used if activated by setting HWSDAFLAGS_MONITORINFO.

FreeMonitorInfo()

Only used if activated by setting HWSDAFLAGS_MONITORINFO.

GrabScreenPixels()

Only used if activated by setting HWSDAFLAGS_GRABSCREEN.

FreeGrabScreenPixels()

Only used if activated by setting HWSDAFLAGS_GRABSCREEN.

BeginDoubleBuffer()

Only used if activated by setting HWSDAFLAGS_DOUBLEBUFFER.

EndDoubleBuffer()

Only used if activated by setting HWSDAFLAGS_DOUBLEBUFFER.

Flip()

Only used if activated by setting HWSDAFLAGS_DOUBLEBUFFER.

Cls()

Only used if activated by setting HWSDAFLAGS_DOUBLEBUFFER.

AllocBitMap()

Only used if activated by setting HWSDAFLAGS_BITMAPADAPTER.

FreeBitMap()

Only used if activated by setting HWSDAFLAGS_BITMAPADAPTER.

LockBitMap()

Only used if activated by setting HWSDAFLAGS_BITMAPADAPTER.

UnLockBitMap()

Only used if activated by setting HWSDAFLAGS_BITMAPADAPTER.

GetBitMapAttr()

Only used if activated by setting HWSDAFLAGS_BITMAPADAPTER.

AllocVideoBitMap()

Only used if activated by setting HWSDAFLAGS_VIDEOBITMAPADAPTER.

FreeVideoBitMap()

Only used if activated by setting HWSDAFLAGS_VIDEOBITMAPADAPTER.

ReadVideoPixels()

Only used if activated by setting HWSDAFLAGS_VIDEOBITMAPADAPTER.

FreeVideoPixels()

Only used if activated by setting HWSDAFLAGS_VIDEOBITMAPADAPTER.

DoVideoBitMapMethod()

Only used if activated by setting HWSDAFLAGS_VIDEOBITMAPADAPTER.

AdapterMainLoop()

Only used if you set the HWEXT_DISPLAYADAPTER_MAINLOOP extension flag. See Extension plugins to learn how to use plugin extension bits.

SetPalette()

Only used if you set the HWEXT_DISPLAYADAPTER_PALETTE extension flag. See Extension plugins to learn how to use plugin extension bits.

SetMenuBar()

Only used if you set the HWEXT_DISPLAYADAPTER_MENUADAPTER extension flag. See Extension plugins to learn how to use plugin extension bits.

SetMenuAttributes()

Only used if you set the HWEXT_DISPLAYADAPTER_MENUADAPTER extension flag. See Extension plugins to learn how to use plugin extension bits.

GetMenuAttributes()

Only used if you set the HWEXT_DISPLAYADAPTER_MENUADAPTER extension flag. See Extension plugins to learn how to use plugin extension bits.

SetTrayIcon()

Only used if you set the HWEXT_DISPLAYADAPTER_TRAYICON extension flag. See Extension plugins to learn how to use plugin extension bits.

OpenPopupMenu()

Only used if you set the HWEXT_DISPLAYADAPTER_POPUPMENU extension flag. See Extension plugins to learn how to use plugin extension bits.

See hw_SetDisplayAdapter for information on how to install your display adapter.

This plugin type is supported since Hollywood 6.0.