Synopsis

ULONG AttachVLayerTagList(
         struct VLayerHandle * VLayerHandle,
         struct Window * Window,
         struct TagItem  * TagItems );

ULONG AttachVLayerTags(
         struct VLayerHandle * VLayerHandle,
         struct Window * Window,
         TAG tag, ... );

Function

Attaches a previously created videolayer handle to the specified window.
The video overlay should now be dynamically linked to the window.
If the window is moved or resized, the overlay is also moved or resized.

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Window - pointer to the window that the videolayer should be attached to

TagItems - pointer to an optional tag list

Result

result - 0 if videolayer could be attached to the window

Notes

Tags available are:

        VOA_LeftIndent (ULONG) - additional offset from the left window border

        VOA_RightIndent (ULONG) - additional offset from the right window border

        VOA_TopIndent (ULONG) - additional offset from the top window border

        VOA_BottomIndent (ULONG) - additional offset from the bottom window border

The source is scaled to the window's inner rectangle minus the
indents. With VOA_UseColorKey the rectangle is filled with the
key colour, and with VOA_UseBackfill a layer backfill hook keeps
it filled.

Detach the layer before the window is closed. Should a window
close with a layer still attached, the library detaches it.

Bugs

Fails while the layer is locked or already attached, when the
window is not on the handle's screen, or when the screen is not
shown on its display.

See also

DetachVLayer()

Synopsis

struct VLayerHandle * CreateVLayerHandleTagList(
         struct Screen * Screen,
         struct TagItem  * TagItems );

struct VLayerHandle * CreateVLayerHandleTags(
         struct Screen * Screen,
         TAG tag, ... );

Function

Creates a video layer handle for the given screen

Inputs

Screen - Screen we wish to create a handle for

TagItems - pointer to an optional tag list

Result

VLayerHandle - pointer to the created videolayer handle or 0

Notes

Tags available are:

        VOA_SrcType (ULONG) - specifies source type that is used for video
                      overlay data

                Currently supported formats:

                        SRCFMT_YUV16 (not recommended, use YCbCr16 instead)
                        SRCFMT_YCbCr16
                        SRCFMT_RGB15PC
                        SRCFMT_RGB16PC
                        SRCFMT_YCbCr420 (planar: a Y plane followed by
                                the U and V planes; width and height
                                must be even; see LockVLayer())
                        SRCFMT_YCbCr420_NV12 (AROS extension: semi-planar,
                                a Y plane followed by one interleaved
                                U,V plane; even sizes; see LockVLayer())

        VOA_ColorSpace (ULONG) - AROS extension: VOCS_BT601 (default),
                VOCS_BT709 or VOCS_BT2020, the matrix a YCbCr source
                was encoded with; a driver may not support
                VOCS_BT2020

        VOA_ColorRange (ULONG) - AROS extension: VOCR_LIMITED
                (default) or VOCR_FULL

        VOA_SrcWidth (ULONG) - source width in pixel units

        VOA_SrcHeight (ULONG) -  source height in pixel units

        VOA_Error (ULONG *) - If you specify VOA_Error with ti_Data pointing
                      to an ULONG, you will get more detailed information
                      if the creation of the video layer handle fails

        VOA_UseColorKey (BOOL) - If you specify VOA_UseColorKey as TRUE, color
                keying is enabled for the video layer. A
                certain color key is generated then and the
                stream data is only visible where this color
                could be found.

        VOA_UseBackFill (BOOL) - If you specify VOA_UseBackFill as TRUE automatic
                backfilling for the videolayer is enabled. This
                option is only available if color keying is
                enabled. AROS: where the display can show the
                layer below the screen (an underlay), the backfill
                makes the window transparent instead and the layer
                goes there, so what the application draws over
                it shows on top; VOA_UseColorKey is then not
                needed.

        VOA_Modulo (ULONG) - bytes per source row (V43). Defaults to
                VOA_SrcWidth * 2. The display backend chooses its
                own pitch; read it back with GetVLayerAttr(VOA_Modulo)
                while the layer is locked (for SRCFMT_YCbCr420 that
                is the Y plane pitch; the chroma pitch is half of it).

        VOA_DoubleBuffer (BOOL) - two buffers, swapped with
                SwapVLayerBuffer() (V43)

        VOA_MultiBuffer (ULONG) - number of buffers (V50)

Error codes:

        VOERR_INVSRCFMT - unknown VOA_SrcType, zero or (planar)
                odd dimensions or a modulo shorter than a source row

        VOERR_INVSCRMODE - the screen's display has no plane for
                the format (no video overlay)

        VOERR_NOOVLMEMORY - the scan-out bitmap could not be
                allocated

        VOERR_NOMEMORY - out of memory

Bugs

Setting the CGXVideoNullBackend variable selects a backend that
keeps the source in system RAM and displays nothing.

See also

QueryVLayerAttr()

Synopsis

void DeleteVLayerHandle(
         struct VLayerHandle * VLayerHandle );

Function

Deletes a created video layer handle

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Result

none

Notes

The handle may still be locked or attached: it is unlocked and
detached first.

See also

CreateVLayerHandleTagList()

Synopsis

ULONG DetachVLayer(
         struct VLayerHandle * VLayerHandle );

Function

Detaches a videolayer from a given window. As a result, the video
overlay should now be unlinked from the window and the original
contents of the window are visible now.

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Result

result - 0 if videolayer could be detached from the window

Notes

The backfill hook installed by AttachVLayerTagList() is removed;
the key colour stays in the window until the application redraws.

Bugs

Fails while the layer is locked or not attached.

See also

AttachVLayerTagList()

Synopsis

IPTR GetVLayerAttr(
         struct VLayerHandle * VLayerHandle,
         ULONG AttrNum );

Function

Gets a certain attribute from a given video layer. You have to call
LockVLayer() to make sure that the result is valid !

Inputs

VLayerHandle - pointer to a previously created videolayer handle

AttrNum - attribute that you want to get

Result

value - the value for the given attribute

Notes

Attributes available are:

VOA_BaseAddress -       if this attribute is specified the base address for
                        the source data is returned

VOA_ColorKeyPen -       returns the pen number used for color keying. If color
                        keying is not enabled, -1 is returned

VOA_ColorKey -  returns the 24 bit color value used for color keying.
                        If color keying is not enabled, -1 is returned.
VOA_Underlay -          AROS extension: TRUE while the layer is shown
                        below the screen (VOA_UseBackfill where the
                        display can), so what is drawn in the window
                        over it shows on top of the video. It can
                        change while the layer is attached.

VOA_Width, VOA_Height - source dimensions in pixels

VOA_Modulo -            bytes per source row (the Y plane pitch for
                        SRCFMT_YCbCr420; the chroma pitch is half)

VOA_BaseOffset0/1/2 -   SRCFMT_YCbCr420: offsets of the Y, U and V
                        planes from VOA_BaseAddress (V50);
                        SRCFMT_YCbCr420_NV12: Y and interleaved UV
                        plane offsets, VOA_BaseOffset2 is 0. Valid
                        after the first LockVLayer(); 0 for other
                        source types.

Bugs

VOA_BaseAddress returns NULL unless the layer is locked. Other
attributes return 0.

See also

SetVLayerAttrTagList()

Synopsis

ULONG LockVLayer(
         struct VLayerHandle * VLayerHandle );

Function

Locks the specified video layer to allow access to source data. Make
sure that you don't keep that lock for too long. It is only allowed
to keep it for a short time.

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Result

result - TRUE if video layer could be locked, FALSE otherwise

Notes

The buffer locked is the one to write next (the back buffer of a
double or multi buffered layer, the only buffer otherwise). Its
address and pitch are read with GetVLayerAttr(VOA_BaseAddress)
and GetVLayerAttr(VOA_Modulo) while locked.

For SRCFMT_YCbCr420 the address is the Y plane (pitch VOA_Modulo);
the U and V planes follow at the offsets GetVLayerAttr(VOA_BaseOffset1)
and GetVLayerAttr(VOA_BaseOffset2) from it, with pitch VOA_Modulo/2
and height/2 rows. Those offsets follow the CGX rule (U = Y +
modulo*height, V = U + (modulo/2)*(height/2)) unless the display
aligns the planes; read them rather than assuming.

For SRCFMT_YCbCr420_NV12 the address is the Y plane (pitch
VOA_Modulo) and the interleaved U,V plane (U byte then V byte per
pixel pair, pitch VOA_Modulo, height/2 rows) is at
GetVLayerAttr(VOA_BaseOffset1); VOA_BaseOffset2 is 0.

Bugs

The lock does not nest; a second LockVLayer() fails until
UnlockVLayer() is called.

See also

UnlockVLayer() SwapVLayerBuffer()

Synopsis

ULONG QueryVLayerAttr(
         struct Screen * Screen,
         ULONG AttrID );

Function

Queries the video layer capabilities of a screen.

Inputs

Screen - screen to query

AttrID - one of:

        VSQ_SupportedFeatures - mask of VSQ_FEAT_... bits

        VSQ_SupportedFormats - mask of VSQ_FMT_... bits
                (VSQ_FMT_NV12 is an AROS extension: the
                semi-planar SRCFMT_YCbCr420_NV12 source)

        VSQ_MaxWidth - maximum source width of an overlay

        VSQ_MaxWidthSP - maximum width of a subpicture

Result

value - the value of the attribute, 0 if unsupported

Notes

Available since V50. VSQ_FEAT_OVERLAY is set when the screen's
display has a plane for YUV sources: packed YUYV (VSQ_FMT_YUYV,
SRCFMT_YCbCr16), planar I420 (VSQ_FMT_YUV420_PLANAR,
SRCFMT_YCbCr420) or semi-planar NV12 (VSQ_FMT_NV12,
SRCFMT_YCbCr420_NV12); VSQ_FEAT_COLORKEYING when that plane supports a destination
colour key, VSQ_FEAT_FILTERING when it scales,
VSQ_FEAT_DOUBLEBUFFER / VSQ_FEAT_MULTIBUFFER from the number of
buffers a scan-out bitmap may have.

Bugs

Subpictures are not supported.

See also

CreateVLayerHandleTagList()

Synopsis

void SetVLayerAttrTagList(
         struct VLayerHandle * VLayerHandle,
         struct TagItem  * TagItems );

void SetVLayerAttrTags(
         struct VLayerHandle * VLayerHandle,
         TAG tag, ... );

Function

Sets certain attributes for a given video layer

Inputs

VLayerHandle - pointer to a previously created videolayer handle

TagItems - pointer to a tag list which contains attributes to be
        modified

Result

none

Notes

Tags available are:

        VOA_LeftIndent (ULONG) - additional offset from the left window
                                        border

        VOA_RightIndent (ULONG) - additional offset from the right window
                                        border

        VOA_TopIndent (ULONG) - additional offset from the top window border

        VOA_BottomIndent (ULONG) - additional offset from the bottom window
                                        border

        VOA_ColorSpace (ULONG) - AROS extension: VOCS_BT601,
                                        VOCS_BT709 or VOCS_BT2020

        VOA_ColorRange (ULONG) - AROS extension: VOCR_LIMITED or
                                        VOCR_FULL

A changed indent moves the overlay at once; a changed colour space
or range applies from the next frame, for a stream that changes its
encoding. Subpicture and colour key tags are ignored.

See also

GetVLayerAttr()

Synopsis

void SwapVLayerBuffer(
         struct VLayerHandle * VLayerHandle );

Function

Swaps the displayed and the rendering buffer of a double buffered
video layer at the next vertical blank. The next LockVLayer() may
wait for that vertical blank.

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Result

none

Notes

Available since V50. Does nothing for a single buffered layer or
while the layer is locked.

See also

LockVLayer() QueryVLayerAttr()

Synopsis

ULONG UnlockVLayer(
         struct VLayerHandle * VLayerHandle );

Function

Unlocks a previouly locked video layer

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Result

result - always 0

Notes

The display may upload or flush the buffer here.

See also

LockVLayer()

Synopsis

ULONG WriteSPLine(
         struct VLayerHandle * VLayerHandle,
         UBYTE * Buffer,
         LONG X,
         LONG Y,
         LONG Width );

Function

Writes one line of subpicture data to a video layer.

Inputs

VLayerHandle - pointer to a previously created videolayer handle

Buffer - subpicture pixel data

X, Y - position of the line in the subpicture

Width - number of pixels to write

Result

result - 0

Notes

Available since V50.

Bugs

No backend supports subpictures yet, so this does nothing.

See also

QueryVLayerAttr()