APTR handle = OpenDisplay(STRPTR title, int x, int y, int width,
                  int height, ULONG flags, struct hwTagList *tags);

Your implementation has to return a handle that is used to refer to this display later or NULL in case an error has occurred.

The flags parameter can be a combination of the following individual flags:

HWDISPFLAGS_BORDERLESS:

Window should be opened without any border decoration.

HWDISPFLAGS_SIZEABLE:

Window should be resizeable. Note that this flag refers to user resizability only. Even if this flag isn't set, Hollywoood might still ask your window to resize by calling the SizeMoveDisplay() function.

HWDISPFLAGS_FIXED:

Window dragging should be disabled.

HWDISPFLAGS_NOHIDE:

Window should not have a widget for minimizing.

HWDISPFLAGS_NOCLOSE:

Window should not have a close widget.

HWDISPFLAGS_AUTOSCALE:

This flag is set if the user has enabled auto scaling for this window. If that is the case, the window's physical dimensions won't necessarily match the dimensions of its back buffer.

HWDISPFLAGS_LAYERSCALE:

This flag is set if the user has enabled layer scaling for this window. Layer scaling uses a different technique than auto scaling which means that the back buffer size will match the window's physical size in case layer scaling is active.

HWDISPFLAGS_LAYERS:

This flag is set if layers are enabled for this window.

HWDISPFLAGS_DOUBLEBUFFER:

This flag is set if Hollywood will use double buffer drawing for this window.

HWDISPFLAGS_HARDWAREDB:

This flag is set if Hollywood is using a hardware double buffer provided by the plugin for this window.

HWDISPFLAGS_FULLSCREEN:

If this flag is set, the display should be opened in full screen mode. You may choose to ignore the x and y parameters in that case.

HWDISPFLAGS_DISABLEBLANKER:

If this flag is set, the screen blanker should be disabled while this display is opened.

HWDISPFLAGS_ALWAYSONTOP:

If this flag is set, the display should always stay on top of other windows. (V7.1)

HWDISPFLAGS_SCALEFACTOR:

If this flag is set, the display has scale factor mode enabled. You can get the scale factor by querying HWDISPATTR_SCALEFACTOR using hw_GetDisplayAttr(). Note that an enabled scale factor mode doesn't necessarily mean that the scale factor is different from 1.0. Scale factor mode can be enabled and the scale factor can still be 1.0 in which case your display should behave as if no scale factor mode was active. (V9.0)

HWDISPFLAG_TRAPRMB:

If this flag is set, the user has set the TrapRMB option to True. (V9.0)

HWDISPFLAG_KEEPPROPORTIONS:

If this flag is set, the user has set the KeepProportions option to True. (V9.0)

Additionally, Hollywood will pass a tag list to OpenDisplay(). This tag list can contain the following tags:

HWDISPTAG_BUFFERWIDTH:

This tag is always provided and contains the pixel width of Hollywood's back buffer for this display. Please note that this is not necessarily the same as the window's physical dimensions. If autoscaling is active, back buffer size and the window's physical dimensions can be different. It is suggested that you allocate a pixel buffer of this size and first draw everything into this back buffer. After that you refresh the display using the graphics you have drawn into the back buffer. For optimized drawing you should implement a custom double buffer using HWPLUG_CAPS_DOUBLEBUFFER. Custom double buffers don't have to draw into the back buffer first because double buffer frames are usually updated multiple times per second so there's no need to cache an additional back buffer for refreshing the window when parts of it have to be redrawn.

HWDISPTAG_BUFFERHEIGHT:

This tag is always provided and contains the pixel height of Hollywood's back buffer for this display. See above for details.

HWDISPTAG_OPTIMIZEDREFRESH:

This tag is always provided and it is set to a pointer to a ULONG. Your plugin can write True to this pointer if it wants Hollywood to enable optimized refresh for this display. Optimized refresh should be enabled on systems where it's more efficient to refresh the complete display instead of several smaller parts. By default, Hollywood prefers to refresh just the parts of the display that actually need refreshing. On some backends, however, this is quite slow if several smaller parts have to be updated. It is often faster to refresh the complete display on these systems. This is especially true for backends that are double buffer based because refreshing a single tile on double buffer based backends means doing a complete buffer flip which doesn't look so nice and is quite slow. That's why it is wise to enable this option on some systems. By default, optimized refresh is disabled.

HWDISPTAG_SINGLEREFRESHFX:

This tag is always provided and it is set to a pointer to a ULONG. Your plugin can write True to this pointer if it wants Hollywood to enable single refresh transition effect drawing for this display. This option is related to the HWDISPTAG_OPTIMIZEDREFRESH tag (see above). If you set the pointer that you are passed here to True, Hollywood will draw one transition effect frame in exactly one video frame. If it is set to False (which is also the default), Hollywood might emit more than one video frame for a single transition effect frame. This is especially so for transition effect frames that consist of many small parts that need to be updated. If HWDISPTAG_SINGLEREFRESHFX is not set to True, Hollywood will prefer to draw many small parts instead of the complete frame all at once. On some systems, however, drawing many small bits totally kills the performance. In that case you need to set this tag to True. See above in HWDISPTAG_OPTIMIZEDREFRESH for additional information.

HWDISPTAG_LUASTATE:

This tag is always provided and contains a pointer to the lua_State.

HWDISPTAG_MONITOR:

This tag is always provided and specifies the monitor that this display should be opened on. Monitors are counted from 0 which specifies the primary monitor.

HWDISPTAG_SCREENWIDTH:

If HWDISPFLAGS_FULLSCREEN has been set, this tag contains the desired pixel width for the full screen mode. This is not necessarily the same as the display width since the user might explicitly choose a full screen resolution that is larger than the display, e.g. an 800x600 screen mode for a 640x480 display.

HWDISPTAG_SCREENHEIGHT:

Contains the desired pixel screen height if HWDISPFLAGS_FULLSCREEN has been set. See above for details.

HWDISPTAG_SCREENDEPTH:

Contains the desired screen depth if HWDISPFLAGS_FULLSCREEN has been set. On most systems you may choose to ignore this since most modern systems all operate in 32-bit true colour mode.

HWDISPTAG_SCALEWIDTH:

If HWDISPFLAGS_AUTOSCALE or HWDISPFLAGS_LAYERSCALE is active, this tag contains the current scale width.

HWDISPTAG_SCALEHEIGHT:

If HWDISPFLAGS_AUTOSCALE or HWDISPFLAGS_LAYERSCALE is active, this tag contains the current scale height.

HWDISPTAG_SCALEMODE:

If HWDISPFLAGS_AUTOSCALE or HWDISPFLAGS_LAYERSCALE is active, this tag contains the current scale mode. Currently, only 0 and 1 are defined here. 0 means hard scaling with no interpolation whereas 1 means anti-alias interpolated scaling.

HWDISPTAG_DEPTH:

Contains the desired pixel depth for the display. This is mostly interesting in palette modes. (V9.0)

HWDISPTAG_PALETTE:

If the display is a palette mode display, the pData member of this tag will be set to a ULONG array containing the display's palette. The individual colors will be stored as RGB values in the palette array. (V9.0)

HWDISPTAG_PALETTEMODE:

If the display is a palette mode display, the pData member of this tag will be set to a pointer to an int. Your display adapter can write the value True to this int to signal that it supports genuine palette mode. A genuine palette mode is a screen mode which is palette-based so that changing a single pen will automatically change all pixels that use that pen. A genuine palette display allows Hollywood to use several optimizations because screen pixels can be changed by just changing color registers, i.e. without copying any actual pixel data. If you enable genuine palette mode, you must also set HWSDAFLAGS_PALETTE and one or both of HWSDAFLAGS_PENDRAW and HWSDAFLAGS_SETPALETTE using hw_SetDisplayAdapter(). See hw_SetDisplayAdapter for details. (V9.0)

HWDISPTAG_MENU:

If a menu bar should be attached to this display, Hollywood will set the pData member of this tag to a struct hwMenuTreeInfo pointer which contains all nodes and leaves of the menu bar. See SetMenuBar for a description of this structure. Whenever the user selects a menu item, you need to post an HWEVT_MENUITEM event to Hollywood's event queue. See hw_PostEvent for details. Note that this tag will only ever be set if your display adapter has signalled that it supports menus by setting the HWSDAFLAGS_MENUADAPTER when calling hw_SetDisplayAdapter(). See hw_SetDisplayAdapter for details. (V9.0)

HWDISPTAG_XPOSITION:

The pData member of this tag is set to a pointer to an int that contains the display's x position. This is identical to the x position passed to your OpenDisplay() implementation. However, if your implementation decides to open the display at a position different to the requested one, you should write the actual x position of your display to the int pointer passed in the pData member of the tag so that Hollywood can get to know the display's real x position. (V9.1)

HWDISPTAG_YPOSITION:

The pData member of this tag is set to a pointer to an int that contains the display's y position. This is identical to the y position passed to your OpenDisplay() implementation. However, if your implementation decides to open the display at a position different to the requested one, you should write the actual y position of your display to the int pointer passed in the pData member of the tag so that Hollywood can get to know the display's real y position. (V9.1)

HWDISPTAG_FLAGS:

The pData member of this tag is set to a pointer to a ULONG that contains the display flags. This is identical to the display flags passed to your OpenDisplay() implementation. However, if your implementation decides to modify the requested display flags in any way (e.g. adding or removing flags), you should write the actual display flags to the ULONG pointer passed in the pData member of the tag so that Hollywood can get to know the display's real flags. (V9.1)

HWDISPTAG_USERTAGS:

If this is set, pData will point to a struct hwUserTagList containing a list of user tags passed by the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. See User tags for details. (V10.0)

Please note that Hollywood supports multiple displays so OpenDisplay() can be called several times. Hollywood also supports multiple full screen displays if they are to appear on different monitors. Be prepared to deal with these cases.

title

caption string for the display's window border

x

desired x position of this display in pixels

y

desired y position of this display in pixels

width

desired width for this display in pixels

height

desired height for this display in pixels

flags

flags describing additional options (see above)

tags

tag list describing additional options (see above)

handle

a handle to the newly allocated display or NULL in case of an error