APTR handle = hw_AttachDisplaySatellite(lua_ID *id, int (*dispatcher)
                  (APTR handle, int op, APTR opdata, APTR userdata),
                  APTR userdata, struct hwTagList *tags);

You have to pass the object identifier of the display the new satellite shall attach to. The object identifier must be passed as a lua_ID. See Object identifiers for details.

You also have to pass a pointer to a dispatcher function which will be called whenever Hollywood draws something to the satellite's root display. In that case, Hollywood will first draw to the root display and then immediately call your satellite's dispatcher so that it is informed about the draw operation. The prototype of this dispatcher function looks like this:

int dispatcher(APTR handle, int op, APTR opdata, APTR userdata);

Hollywood will pass a handle to the display satellite in the first parameter and it will pass the user data that you specified in your call to hw_AttachDisplaySatellite() in the fourth parameter. Parameters 2 and 3 contain the information about the operation that Hollywood wants your satellite to execute. The data passed in opdata depends on the actual operation passed in parameter 2. The following operations are currently recognized:

HWSATOP_BLTBITMAP:

Hollywood wants your satellite to blit a bitmap to its graphics buffer. opdata will get a pointer to a struct hwSatelliteBltBitMap which contains all information you need to do the blit operation. struct hwSatelliteBltBitMap looks like this:

struct hwSatelliteBltBitMap { APTR BitMap; // [in] int BitMapType; // [in] int BitMapWidth; // [in] int BitMapHeight; // [in] int BitMapModulo; // [in] int BitMapPixFmt; // [in] UBYTE *Mask; // [in] int MaskModulo; // [in] int SrcX; // [in] int SrcY; // [in] int DstX; // [in] int DstY; // [in] int Width; // [in] int Height; // [in] ULONG *Palette; // [in] -- V9.0 };

The structure members will be initialized as follows:

BitMap:

This will be set to a pointer to the bitmap that shall be blitted. The actual type of the bitmap specified here is specified in the BitMapType member (see below).

BitMapType:

This contains the type of the bitmap pointer passed in the BitMap member. The following types are currently supported:

HWSATBMTYPE_AMIGABITMAP:

HWSATBMTYPE_AMIGABITMAP indicates that the bitmap is an AmigaOS bitmap, i.e. a struct BitMap allocated by graphics.library/AllocBitMap(). This can only happen on AmigaOS based systems.

HWSATBMTYPE_PIXELBUFFER:

The bitmap is a raw pixel buffer. The actual format of the raw pixels is specified in the BitMapPixFmt structure member.

HWSATBMTYPE_VIDEOBITMAP:

The bitmap is a video bitmap allocated by your plugin's AllocVideoBitMap() function. (V6.0)

HWSATBMTYPE_BITMAP:

The bitmap is a Hollywood bitmap. Use hw_LockBitMap() to access its pixels. (V6.0)

HWSATBMTYPE_CLUTBITMAP:

The bitmap is a CLUT bitmap. Use hw_LockBitMap() to access its pixels. Note that this can only ever happen if you have set HWADS_PALETTE to True when calling hw_AttachDisplaySatellite(). Otherwise you will never be passed CLUT bitmaps. The CLUT bitmap's palette will be stored in the palette structure member (see below). (V9.0)

BitMapWidth:

Contains the bitmap's width in pixels.

BitMapHeight:

Contains the bitmap's height in pixels.

BitMapModulo:

Contains the bitmap's modulo width in pixels, i.e. the pixel of one row of image data. This is often more than what is passed in BitMapWidth because row padding is used. BitMapModulo only contains a meaningful value if BitMapType has been set to HWSATBMTYPE_PIXELBUFFER.

BitMapPixFmt:

Contains the pixel format of the raw pixels passed in the BitMap structure member. This only contains a meaningful value if BitMapType has been set to HWSATBMTYPE_PIXELBUFFER. See Pixel format information for a list of pixel formats.

MaskData:

If this does not equal NULL, Hollywood wants you to take this mask into account when blitting. MaskData points to an array of raw mask bits then (1 bit per pixel). This array matches the size of the bitmap passed in the BitMap member. Hollywood masks only know two different states: visible (1) and invisible (0) pixels. The bits are stored from left to right in chunks of one byte, i.e. the most significant bit of the first byte describes the transparency setting of the first pixel. The number of bytes per row is stored in the MaskModulo member (see below).

MaskModulo:

If MaskData contains a mask pointer, this member will be set to the number of bytes that is used for one row of mask data. Note that this value is specified in bytes and often contains some padding.

SrcX:

Contains the source x-offset of the blit operation.

SrcY:

Contains the source y-offset of the blit operation.

DstX:

Contains the destination x-offset of the blit operation.

DstY:

Contains the destination y-offset of the blit operation.

Width:

Contains the number of columns to blit.

Height:

Contains the number of rows to blit.

Palette:

Contains the palette of the CLUT bitmap if BitMapType is HWSATBMTYPE_CLUTBITMAP. The palette colors are stored as raw RGB values in the ULONG array. Note that Palette can only ever be set if you have set HWADS_PALETTE to True when calling hw_AttachDisplaySatellite(). Otherwise you will never be passed CLUT bitmaps. (V9.0)

Please note that you do not have to do any clipping. Hollywood will clip all coordinates against your satellite root display's boundaries before invoking your dispatcher.

HWSATOP_RECTFILL:

Hollywood wants your satellite to draw a rectangle to its graphics buffer. opdata will get a pointer to a struct hwSatelliteRectFill which contains all information you need to do this operation. struct hwSatelliteRectFill looks like this:

struct hwSatelliteRectFill { int X; int Y; int Width; int Height; ULONG Color; };

The structure members will be initialized as follows:

X:

Start x-offset of the rectangle to fill.

Y:

Start y-offset of the rectangle to fill.

Width:

Width in pixels of the area to fill.

Height:

Height in pixels of the area to fill.

Color:

Filling color specified as a 24-bit RGB value.

Please note that you do not have to do any clipping. Hollywood will clip all coordinates against your satellite root display's boundaries before invoking your dispatcher.

HWSATOP_LINE:

Hollywood wants your satellite to draw a line to its graphics buffer. opdata will get a pointer to a struct hwSatelliteLine which contains all information you need to do this operation. struct hwSatelliteLine looks like this:

struct hwSatelliteLine { int X1; int Y1; int X2; int Y2; ULONG Color; };

The structure members will be initialized as follows:

X1:

Start x-offset for the line.

Y1:

Start y-offset for the line.

X2:

End x-offset for the line.

Y2:

End y-offset for the line.

Color:

Desired line color specified as a 24-bit RGB value.

Please note that you do not have to do any clipping. Hollywood will clip all coordinates against your satellite root display's boundaries before invoking your dispatcher.

HWSATOP_WRITEPIXEL:

Hollywood wants your satellite to draw a single pixel to its graphics buffer. opdata will get a pointer to a struct hwSatelliteWritePixel which contains all information you need to do this operation. struct hwSatelliteWritePixel looks like this:

struct hwSatelliteWritePixel { int X; int Y; ULONG Color; };

The structure members will be initialized as follows:

X:

Pixel's x-offset.

Y:

Pixel's y-offset.

Color:

Pixel color specified as a 24-bit RGB value.

Please note that you do not have to do any clipping. Hollywood will clip all coordinates against your satellite root display's boundaries before invoking your dispatcher.

HWSATOP_RESIZE:

Hollywood wants your display satellite to resize. opdata will get a pointer to a struct hwSatelliteResize which contains all information you need to do this operation. struct hwSatelliteResize looks like this:

struct hwSatelliteResize { int Width; int Height; };

The structure members will be initialized like this:

Width:

This member contains the new display satellite width in pixels.

Height:

This member contains the new display satellite height in pixels.

HWSATOP_VWAIT:

This opcode is only sent if your display satellite has explicitly requested to be notified whenever its root display is asked to wait for the vertical blank interrupt by setting the HWADS_DISPATCHVWAIT tag to True. If that is the case, you will receive this opcode whenever a vertical blank wait is executed on the satellite's root display. This notification can come in handy in case the root display is hidden and doesn't execute any vertical blank waits. You could then do this job in your satellite dispatcher to prevent Hollywood from running too fast. (V6.0)

HWSATOP_SETPOINTER:

Hollywood wants your satellite to change the mouse pointer. opdata will be set to a pointer to a struct hwSatelliteSetPointer which contains all information you need to change the pointer. struct hwSatelliteSetPointer looks like this:

struct hwSatelliteSetPointer { int Type; APTR Handle; };

The structure members will be initialized as follows:

Type:

This member will be initialized to one of the following pointer types:

HWPOINTER_SYSTEM HWPOINTER_BUSY HWPOINTER_CUSTOM

Handle:

If Type has been set to HWPOINTER_CUSTOM, Handle will be set to the pointer's handle, as allocated by CreatePointer().

Note that HWSATOP_SETPOINTER will only be dispatched if you have set the HWADS_MOUSEPOINTER tag to True (see below). (V9.0)

HWSATOP_SHOWHIDEPOINTER:

Hollywood wants your satellite to show or hide the mouse pointer. opdata will be set to a pointer to a struct hwSatelliteShowHidePointer which contains the information whether to show or hide the pointer. struct hwSatelliteShowHidePointer looks like this:

struct hwSatelliteShowHidePointer { int Show; };

The structure members will be initialized as follows:

Show:

This will be True if the pointer shouldn't be shown, False if it should be hidden.

Note that HWSATOP_SHOWHIDEPOINTER will only be dispatched if you have set the HWADS_MOUSEPOINTER tag to True (see below). (V9.0)

HWSATOP_MOVEPOINTER:

Hollywood wants your satellite to move the mouse pointer. opdata will be set to a pointer to a struct hwSatelliteMovePointer which contains the information about the new pointer position. struct hwSatelliteMovePointer looks like this:

struct hwSatelliteMovePointer { int X; int Y; };

The structure members will be initialized as follows:

X:

The new x position for the mouse pointer.

Y:

The new y position for the mouse pointer.

Note that HWSATOP_MOVEPOINTER will only be dispatched if you have set the HWADS_MOUSEPOINTER tag to True (see below). (V9.0)

Finally, hw_AttachDisplaySatellite() also accepts a tag list which allows you to configure some further options. The following tags are currently recognized:

HWADS_WIDTH:

If you specify this tag, you need to set its pData member to a pointer to an int. hw_AttachDisplaySatellite() will then write the root display's pixel width to this int.

HWADS_HEIGHT:

If you specify this tag, you need to set its pData member to a pointer to an int. hw_AttachDisplaySatellite() will then write the root display's pixel height to this int.

HWADS_DISPATCHVWAIT:

This tag allows you to control whether or not you want to be notified when the root display waits for the vertical blank. By default, you won't be notified about this event but if you set the iData member of this tag to True, Hollywood will dispatch the HWSATOP_VWAIT operation to your satellite dispatcher whenever its root display waits for the vertical blank interrupt (see above). (V6.0)

HWADS_OPTIMIZEDREFRESH:

Set this tag to True to force optimized refresh of this display satellite's parent. See OpenDisplay for more information on optimized refresh. (V6.1)

HWADS_CUSTOMSCALING:

Set this tag to True if your dispatcher will handle autoscaling for this satellite. In this case, Hollywood won't do any autoscaling but will simply tell the dispatcher to do so. Note that this tag only affects autoscaling, layer scaling will always be done by Hollywood. If your dispatcher implements custom scaling, the dimensions returned by HWADS_WIDTH and HWADS_HEIGHT reflect the destination scaling size and the dimensions returned by HWADS_BUFFERWIDTH and HWADS_BUFFERHEIGHT reflect the source size. (V8.0)

HWADS_BUFFERWIDTH:

This tag can be used to get the width of the display satellite's parent's back buffer. This can be different from what is returned in HWADS_WIDTH in case autoscaling is active. The return value will be written to the pData member of this tag. You must set pData to an int pointer for this purpose. (V8.0)

HWADS_BUFFERHEIGHT:

This tag can be used to get the height of the display satellite's parent's back buffer. This can be different from what is returned in HWADS_HEIGHT in case autoscaling is active. The return value will be written to the pData member of this tag. You must set pData to an int pointer for this purpose. (V8.0)

HWADS_PALETTE:

Set this tag to True to indicate that your dispatcher can handle CLUT bitmaps as well, i.e. HWSATOP_BLTBITMAP is able to deal with CLUT bitmaps. (V9.0)

HWADS_MOUSEPOINTER:

Set this tag to True to indicate that your dispatcher wants to be notified about mouse pointer operations as well. If HWADS_MOUSEPOINTER is True, your dispatcher needs to handle the mouse pointer operations HWSATOP_SETPOINTER, HWSATOP_SHOWHIDEPOINTER, and HWSATOP_MOVEPOINTER as well. (V9.0)

Note that Hollywood versions prior to 6.0 did not check the tag list pointer against NULL so make sure to pass a tag list even if there are no tags in it.

To detach your satellite from its root display, call the hw_DetachDisplaySatellite() function. See hw_DetachDisplaySatellite for details. The user won't be able to free the root display until all satellites have been detached.

id

object identifier of the display you want to attach to

dispatcher

function to handle satellite actions (see above)

userdata

userdata to be passed to the dispatcher function

tags

taglist containing additional arguments; should not be NULL (see above)

handle

handle to the display satellite or NULL on error