User’s Manual

EMMA2 API

OSD

CONTENTS

1 Introduction ....................................................................................................................... 3
2 Function Prototypes .......................................................................................................... 6
MMAC_OSD_Initialise ..................................................................................................6
MMAC_OSD_SetMode.................................................................................................7
MMAC_OSD_SetBlitSyncMode....................................................................................8
MMAC_OSD_CreateRegion .........................................................................................9
MMAC_OSD_DeleteRegion .......................................................................................11
MMAC_OSD_ShowRegion.........................................................................................12
MMAC_OSD_MoveRegion .........................................................................................13
MMAC_OSD_BltToRegion .........................................................................................14
MMAC_OSD_BltFromRegion .....................................................................................16
MMAC_OSD_BltFill ....................................................................................................18
MMAC_OSD_InstallBltCallback..................................................................................19
MMAC_OSD_SetRegionPixel.....................................................................................20
MMAC_OSD_GetRegionPixel ....................................................................................21
MMAC_OSD_PlotPoints .............................................................................................22
MMAC_OSD_FillRect .................................................................................................24
MMAC_OSD_FrameRect ...........................................................................................25
MMAC_OSD_CopyRect .............................................................................................27
MMAC_OSD_SetRegionAlpha ...................................................................................28
MMAC_OSD_SetClutAlpha ........................................................................................29
MMAC_OSD_SetRegionClutTransparency................................................................30
MMAC_OSD_SetPalette.............................................................................................31
MMAC_OSD_SetPaletteEntry ....................................................................................32

Book No. S16753EE1V0UM00 Doc No: MMAC0028, Issue: 1.2

© NEC Electronics Corporation 2002 ~ 2004 Publication Date: 2004-02-11
The information is this document is subject to change without notice – it is
the reader’s responsibility to check that this is the latest available version.

This document includes company confidential information. It should only be

released to third parties under a Non-Disclosure Agreemant.
 MMAC_OSD_GetPaletteEntry....................................................................................33
MMAC_OSD_Reset....................................................................................................34
MMAC_OSD_SetTiling ...............................................................................................35
MMAC_OSD_GetTiling...............................................................................................36
MMAC_OSD_SetAlut..................................................................................................37
MMAC_OSD_SetAlutEntry .........................................................................................38
MMAC_OSD_GetAlutEntry.........................................................................................39
MMAC_OSD_GetRegionInfo ......................................................................................40
MMAC_OSD_AssociatePlane ....................................................................................41
3 Data Structures ............................................................................................................... 42
4 Revision History .............................................................................................................. 46

2
1 Introduction
This section defines the API for the MMAC OSD driver. Prior to using any of the functions of this section
it is necessary to initialise the other parts of the driver that this code depends on by calling:
MMAC_RTOS_Initialise()
MMAC_DMA_Initialise()
MMAC_VIDENC_Initialise ()
MMAC_VIDEO_Initialise()

The video should also be configured by calling MMAC_VIDEO_SetConfiguration().

The API function MMAC_OSD_Initialise() must be called prior to any other function. Normally one or
more regions should then be created using MMAC_OSD_CreateRegion(); the individual regions added
to the display list using MMAC_OSD_ShowRegion(), if it is the first region to be displayed then the
OSD display will be automatically turned on. The whole display of an OSD plane may be enabled or
disabled by using MMAC_DISP_Display(). The various operations may be performed on the regions by
using the handle returned from MMAC_OSD_CreateRegion().
Once having created a region it is necessary to create a palette and activate this by using
MMAC_OSD_SetPalette(), until this is done the region cannot be shown.
The API allows for the use of transparency and alpha blending. These have similar effects, the difference
being the degree of transparency that affects the luma value that results in a ‘fade to black’ whereas the
alpha blending also acts on the chroma causing a fade but with constant colour.
The region can be set to interlaced or non-interlaced mode - this mode is independent of the video set-up.
When in interlaced mode, which is the default, the image has twice the resolution of non-interlaced mode.
This is because in non-interlaced mode each line of the region is displayed on two lines of the display, the
odd and even fields, whereas in interlaced mode each field line is from a different line of the region.
Therefore, if non-interlaced mode is used the aspect ratio is inherently changed so any vertical dimensions
will be doubled.
The driver supports two OSD planes independently. This allows regions to be created on the same scanline
if they are created in the different planes. When the region is created the plane in which to place the region
must be specified, thereafter the driver maintains the information internally.
The MMAC_OSD_Reset() function is provided for completeness so that in the event of the OSD
subsystem malfunctioning an individual reset can be applied.
The normal procedure to follow when creating OSD is as follows:
Initialise the sections of the API, which will be used explicitly or by the OSD:
MMAC_RTOS_Initialise()
MMAC_DMA_Initialise()
MMAC_VIDEO_Initialise()
MMAC_VIDEO_SetConfiguration()
MMAC_OSD_Initialise()

Region creation and display:

MMAC_OSD_CreateRegion()
MMAC_OSD_SetPalette()
MMAC_OSD_ShowRegion()

3
To blit a bitmap to the screen, install a callback to be run on completion of the blit then do the blit.
MMAC_OSD_InstallBltCallback()
MMAC_OSD_BltToRegion()

Wait for the blit to complete.

Perform other OSD operations.

When the region is no longer required delete it, this implicitly hides the region and if it is the only region
disables the OSD display for that plane:
MMAC_OSD_DeleteRegion()

The OSD API provides the following functions:

Function Name Description

MMAC_OSD_Initialise This function initialises the OSD subsystem.
MMAC_OSD_SetMode This function sets even and odd field address pointers to
the appropriate addresses.
MMAC_OSD_CreateRegion This function creates a region in the chosen OSD plane
and initialises the data to colour index zero.
MMAC_OSD_BlitSyncMode This function sets synchronous mode of blitter transfer.
MMAC_OSD_DeleteRegion This function deletes a single region specified by
regionID from the OSD plane.
MMAC_OSD_ShowRegion This function displays or hides the specified region.
MMAC_OSD_MoveRegion This function moves an existing region from its current
position given by the point.
MMAC_OSD_BltToRegion This function blits a bitmap to a region in the OSD plane.
MMAC_OSD_BltFromRegion This function blits the contents of a rectangle within a
region from the OSD plane to CPU memory.
MMAC_OSD_BltFill This function fills a rectangle within a region in the OSD
plane by repeating the 4 bytes of pixel information from
input data.
MMAC_OSD_InstallBltCallback This function installs a callback function that will be called
when the blitter has completed performing a blit request.
MMAC_OSD_SetRegionPixel This function sets the single pixel at the address given to
the colour index provided.
MMAC_OSD_GetRegionPixel This function gets the colour of the single pixel at the
address given.
MMAC_OSD_PlotPoints This function plots a number of contiguous points from
the list of points provided in points, starting from the point
specified by startPoint.
MMAC_OSD_FillRect This function draws a filled rectangle within a region on
the screen.
MMAC_OSD_FrameRect This function draws a frame rectangle with lines of width
penWidth in colour colourIndex within the region regionID
on the screen.
MMAC_OSD_CopyRect This function copies a rectangle defined by rect from the
region srcRegionID.
MMAC_OSD_SetRegionAlpha This function sets the Alpha Blending value for the

4
Function Name Description
region.
MMAC_OSD_SetClutAlpha This function sets the Alpha Blending switch.
MMAC_OSD_ This function applies a transparency value to a region in
SetRegionClutTransparency the OSD plane.
MMAC_OSD_SetPalette This function accepts the palette information for the
specified region and manipulates the data to place in the
internal CLUT.
MMAC_OSD_SetPaletteEntry This function accepts the single palette entry for the
specified region and manipulates the data to place in the
internal CLUT in the place specified by index.
MMAC_OSD_GetPaletteEntry This function returns the contents of a single palette entry
specified by index in the specified region regionID.
MMAC_OSD_Reset¤ This function resets the OSD subsystem.
MMAC_OSD_SetTiling This function sets size of the tiling and enable or disable
of the tiling.
MMAC_OSD_GetTiling This function gets size of the tiling and enable or disable
of the tiling.
MMAC_OSD_SetAlut This function accepts the ALUT information for the
specified region and manipulates the data to place in the
internal ALUT.
MMAC_OSD_SetAlutEntry This function accepts the ALUT entry for the specified
region and manipulates the data to place in the internal
ALUT in the place specified by index.
MMAC_OSD_GetAlutEntry This function returns the contents of an ALUT entry
specified.
MMAC_OSD_GetRegionInfo This function returns information about the OSD region
identified by regionID.
MMAC_OSD_AssociatePlane This function associates a virtual plane to a physical
hardware plane.

5
2 Function Prototypes

MMAC_OSD_Initialise

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_Initialise(void)

Includes
#include “mmac/osd.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_ALREADY_INITIALISED

Description
This function initialises the OSD subsystem and must be called once; prior to using any of the other OSD
API functions. If it is called again it will return MMAC_OSD_ALREADY_INITIALISED and perform no
actions.

See Also
MMAC_AUDIO_Initialise
MMAC_VIDEO_Initialise

Sample Code
< tba >

6
MMAC_OSD_SetMode

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetMode(
MMAC_OSD_PLANE plane,
MMAC_BOOL interlaced
)

Includes
#include “mmac/osd.h”

Inputs
plane Selects which of the two OSD planes to interlaced or non-interlaced.
interlaced If MMAC_TRUE sets the OSD into interlaced mode otherwise set non-interlaced.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_NOT_INITIALISED

Description
This sets the even and odd field address pointers to the appropriate addresses (both point to Even OSD
address for non-interlaced, point to Even and Odd OSD memory areas for Interlaced). This means that a
higher definition can be attained in interlaced mode since alternate field lines use the two different banks
of memory for data whereas in non-interlaced mode the same information is used for consecutive pair field
lines. The default setting is interlaced. In interlaced mode the 1:1 aspect ratio of an image is preserved
when it is displayed on the screen, in non-interlaced mode however, the image size is doubled in the y
dimension, so for this mode any bitmaps used must be field bitmaps. The function
MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will be
returned.

See Also
MMAC_OSD_Initialise

Sample Code
< tba >

7
MMAC_OSD_SetBlitSyncMode

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetBlitSyncMode(
MMAC_BOOL synced
)

Includes
#include “mmac/osd.h”

Inputs
synced If MMAC_TRUE then all blit calls are synchronous, else all blit calls are
asynchronous.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_NOT_INITIALISED

Description
This function sets synchronous mode of blitter transfer.
If synchronous mode is selected, blitter transfer function will not return until transfer is completed.
If asynchronous mode is selected, blitter transfer functon soon returns before transfer is completed.
If callback function is installed using MMAC_OSD_InstallBltCallback(), callback will occur when
blitter transfer is finished.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned.

See Also
MMAC_OSD_Initialise
MMAC_OSD_InstallBltCallback
MMAC_OSD_BltToRegion
MMAC_OSD_BltToScreen
MMAC_OSD_BltFill

Sample Code
< tba >

8
MMAC_OSD_CreateRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_CreateRegion(
MMAC_OSD_PLANE plane,
MMAC_OSD_RECT *rect,
MMAC_OSD_BITSPIXEL bitsPix,
MMAC_OSD_REGION *regionID,
MMAC_OSD_ALUT_MODE alutMode,
MMAC_OSD_CLUT_MODE clutMode
)

Includes
#include “mmac/osd.h”

Inputs
plane Determines which of the two OSD planes the region will be created in.
rect Co-ordinates of region relative to screen co-ordinates.
bitsPix Colour mode for region 1/2/4/8bpp CLUT, RGB15, RGB16, RGB32.
regionID Pointer to region created.
alutMode alpha look up table mode. One of:
MMAC_OSD_ALUT_NONE
MMAC_OSD_ALUT_6
MMAC_OSD_ALUT_8
clutMode colour look up table mode. One of:
MMAC_OSD_CLUT_NONE
MMAC_OSD_CLUT_888
MMAC_OSD_CLUT_644_X17COMPATIBLE
MMAC_OSD_CLUT_644_X17WITHEXCEPTION
MMAC_OSD_CLUT_644_X16
MMAC_OSD_CLUT_644_X17_8

Outputs
regionID Identifier of region just created.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INSUFFICIENT_MEMORY
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
This function creates a region in the chosen OSD plane and initialises the data to colour index zero this
will cause the displayed region to be filled with the colour from palette entry zero which should be
initialised by calling MMAC_OSD_SetPalette() prior to showing the region with
MMAC_OSD_ShowRegion(). The function MMAC_OSD_Initialise() must be called first otherwise
MMAC_OSD_NOT_INITIALISED will be returned.

9
Multiple regions in the same plane may not be displayed on the same scan line of the display, nor may the
regions overlap, nor may the region be off screen in any part. The region width must also be at least byte
aligned. If any of these rules are infringed then the value MMAC_OSD_INVALID_REGION is returned.
The function allocates system memory to store the OSD region, if the memory is exhausted then the
function will clean up, then return with MMAC_OSD_INSUFFICIENT_MEMORY.
The returned identifier regionID should be used in all future references to this region.
If no region is created then regionID will be NULL.

Region 3

Region 1

Region 2

Allowed

This function adds Alpha look up table setting and Colour look up table setting.
The combination allowed is as follows. If the other combination is specified then
MMAC_OSD_INVALID_REGION will be returned.

bitsPix alutMode clutMode

MMAC_OSD_BITSPIX1 MMAC_OSD_ALUT_NONE MMAC_OSD_CLUT_888
MMAC_OSD_BITSPIX2 MMAC_OSD_ALUT_6 MMAC_OSD_CLUT_644_
MMAC_OSD_BITSPIX4 MMAC_OSD_ALUT_8 X17COMPATIBLE
MMAC_OSD_BITSPIX8 MMAC_OSD_CLUT_644_
X17WITHEXCEPTION
MMAC_OSD_CLUT_644_X16
MMAC_OSD_CLUT_644_X17_8
MMAC_OSD_RGB15 MMAC_OSD_ALUT_NONE MMAC_OSD_CLUT_NONE
MMAC_OSD_RGB16 MMAC_OSD_ALUT_NONE MMAC_OSD_CLUT_NONE
MMAC_OSD_RGB32 MMAC_OSD_ALUT_NONE MMAC_OSD_CLUT_NONE
MMAC_OSD_ALUT_8

MMAC_OSD_SetPalette, MMAC_OSD_SetPaletteEntry, MMAC_OSD_GetPaletteEntry,

MMAC_OSD_SetAlut, MMAC_OSD_SetAlutEntry and MMAC_OSD_GetAlutEntry will act according
to alutMode and clutMode set by this function.

See Also
MMAC_OSD_DeleteRegion
MMAC_OSD_Initialise

Sample Code
< tba >

10
MMAC_OSD_DeleteRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_DeleteRegion(
MMAC_OSD_REGION regionID
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Defined region on screen.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
This function deletes a single region specified by regionID from the OSD plane. This function
automatically calls MMAC_OSD_ShowRegion to disable the display of the region if it was on display on
entry to this function. The function MMAC_OSD_Initialise() must be called first otherwise
MMAC_OSD_NOT_INITIALISED will be returned, followed by MMAC_OSD_CreateRegion() to obtain
a region handle regionID, otherwise the value MMAC_OSD_INVALID_REGION will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_ShowRegion
MMAC_OSD_Initialise

Sample Code
< tba >

11
MMAC_OSD_ShowRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_ShowRegion(
MMAC_OSD_REGION regionID,
MMAC_BOOL enableFlag
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Defined region on screen.
EnableFlag If MMAC_TRUE enables the display of the OSD Region else it is hidden.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PALETTE

Description
This function displays or hides the specified region. The function MMAC_OSD_Initialise() must be
called first otherwise MMAC_OSD_NOT_INITIALISED will be returned, followed by
MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the value
MMAC_OSD_INVALID_REGION will be returned. The function MMAC_OSD_SetPalette() should be
called for each region prior to showing the region otherwise MMAC_OSD_INVALID_PALETTE will be
returned, however if the region is using 256 colour mode the upper 240 colours of the palette need only be
specified once.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

12
MMAC_OSD_MoveRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_MoveRegion(
MMAC_OSD_REGION regionID,
MMAC_OSD_POINT point
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Point New points co-ordinates for the top left corner of the region.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_POSITION
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
This function moves an existing region from its current position to the position given by the point. It is
allowed however for the region to be moved to a new position which overlaps its existing position or is on
the same scan line as its current position.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise if the regionID cannot be found in the internal list of regions, the value
MMAC_OSD_INVALID_REGION will be returned.
If the region is invalid, because it overlaps another region the value MMAC_OSD_INVALID_REGION is
returned.
If the destination for the move would cause the region to be off-screen in any part then
MMAC_OSD_INVALID_POSITION will be returned. In each case the region remains in the original
position.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

13
MMAC_OSD_BltToRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_BltToRegion(
MMAC_OSD_REGION regionID,
MMAC_OSD_RECT *srcRect,
MMAC_OSD_RECT *destRect,
UI16 linePitch,
MMAC_OSD_BITMAP_FORMAT format,
UI8 *data
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
SrcRect Area within bitmap to copy from.
destRect Area within region to blit to.
linePitch The number bytes separating each start of scanline. (Not supported)
format Format of bitmap. (Not supported)
data Pointer to bitmap structure.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_RECT
MMAC_OSD_BLITTER_BUSY

Description
This function blits a bitmap to a region in the OSD plane. The function MMAC_OSD_Initialise() must be
called first otherwise MMAC_OSD_NOT_INITIALISED will be returned, followed by
MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the value
MMAC_OSD_INVALID_REGION will be returned.
No re-sizing of the bitmap will occur so:
1 For bitmap of type MMAC_OSD_OTV_PIXMAP if the dimensions of destRect are larger than the
bitmap then tiling will occur,
1. If smaller then clipping will occur for all bitmaps.
2. If the srcRect is set with zero for each of the co-ordinates then the entire bitmap will be used,
3. otherwise a portion of the bitmap will be copied. For a bitmap of format MMAC_OSD_BITMAP the
source entry co-ordinates values are limited to the own co-ordinates or boundary co-ordinates of that

14
 bitmap (obtained from a previous blitted from region or indicated with all zero). Other different values
of srcRect for this format will result in a default blitted.
4. If the destRect falls totally outside of the region then the value MMAC_OSD_INVALID_RECT will be
returned.
Bitmaps may be held in memory as non-contiguous blocks, linePitch specifies the number of bytes
separating the start of each scanline in CPU memory. Note: If the whole of the source bitmap is not used,
i.e. source clipped, then the bitmap will have to be processed by the CPU rather than using the blit engine
and in consequence will suffer a performance hit.
If the function is called while the blitter is busy then MMAC_OSD_BLITTER_BUSY will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_BltFromRegion
MMAC_OSD_InstallBltCallback
MMAC_OSD_Initialise
MMAC_OSD_SetBlitSyncMode

Sample Code
< tba >

15
MMAC_OSD_BltFromRegion

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_BltFromRegion(
MMAC_OSD_REGION regionID,
MMAC_OSD_RECT *rect,
UI16 linePitch,
UI8 *data
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Rect Area within region to blit from.
LinePitch The number bytes required to hold each scanline. (Not supported)
Data Destination for data in CPU memory.

Outputs
Data The OSD bitmap data is passed back in the buffer pointed to by this pointer.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_RECT
MMAC_OSD_BLITTER_BUSY

Description
This function blits the contents of a rectangle within a region from the OSD plane to CPU memory. The
function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will
be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise
the value MMAC_OSD_INVALID_REGION will be returned.
If the rect falls totally outside of the region then the value MMAC_OSD_INVALID_RECT will be returned.
The value in linePitch specifies how many bytes are required to hold each scanline. This may be set as the
actual width, or zero for default.
If the function is called while the blitter is busy then the value MMAC_OSD_BLITTER_BUSY will be
returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_BltToRegion
MMAC_OSD_InstallBltCallback
MMAC_OSD_Initialise
MMAC_OSD_SetBlitSyncMode

Sample Code
< tba >

16
17
MMAC_OSD_BltFill

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_BltFill(
MMAC_OSD_REGION regionID,
MMAC_OSD_RECT *rect,
UI32 data
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Rect Area within region to fill.
Data 4 bytes of data used to fill rectangle.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_RECT

Description
This function fills a rectangle within a region in the OSD plane by repeating the 4 bytes of pixel
information from data. The function MMAC_OSD_Initialise() must be called first otherwise
MMAC_OSD_NOT_INITIALISED will be returned, followed by MMAC_OSD_CreateRegion() to obtain a
region handle regionID, otherwise the value MMAC_OSD_INVALID_REGION will be returned.
If the rectangle passed as rect is outside of the region then MMAC_OSD_INVALID_RECT will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_BltToScreen
MMAC_OSD_InstallBltCallback
MMAC_OSD_Initialise
MMAC_OSD_SetBlitSyncMode

Sample Code
< tba >

18
MMAC_OSD_InstallBltCallback

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_InstallBltCallback(
MMAC_OSD_BITBLT_CALLBACK function
)

Includes
#include “mmac/osd.h”

Inputs
Function Pointer to callback function.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_NOT_INITIALISED

Description
This function installs a callback function that will be called when the blitter has completed performing a
blit request. The function once installed will remain installed until the function is called again but with a
NULL pointer for the function parameter. This callback will only be necessary when the function
specifically uses the blit engine as the reason for its existence is to prevent such problems as the CPU
writing to the screen. Supposedly on top of a previously blitted area, but due to a possible delay with the
blitter the CPU action may happen first.
To maintain independence of implementation detail all ‘Blt’ functions will call the callback function if it
exists, whether or not the blit engine is used.
The callback itself must perform a minimum of processing since it is called from an ISR.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_BltToRegion
MMAC_OSD_BltToScreen
MMAC_OSD_BltFill
MMAC_OSD_Initialise
MMAC_OSD_SetBlitSyncMode

Sample Code
< tba >

19
MMAC_OSD_SetRegionPixel

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetRegionPixel(
MMAC_OSD_REGION regionID,
MMAC_OSD_POINT point,
MMAC_OSD_COLOUR *colour
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Point x,y position of pixel within region to set to colour index.
Colour Colour index within palette or RGB table.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_POSITION

Description
This function sets the single pixel at the address given to the colour index provided. The function
MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will be
returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the
value MMAC_OSD_INVALID_REGION will be returned. If the point is outside of the region then
MMAC_OSD_INVALID_POSITION will be returned.

See Also
MMAC_OSD_GetRegionPixel
MMAC_OSD_Initialise

Sample Code
< tba >

20
MMAC_OSD_GetRegionPixel

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_GetRegionPixel(
MMAC_OSD_REGION regionID,
MMAC_OSD_POINT point,
MMAC_OSD_COLOUR *colour
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Point x,y position of pixel within region to get colour index.

Outputs
Colour Pointer to Colour index or RGB table returned for the required pixel.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_POSITION

Description
This function gets the colour of the single pixel at the address given. The function
MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will be
returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the
value MMAC_OSD_INVALID_REGION will be returned. If the point is outside of the region then
MMAC_OSD_INVALID_POSITION will be returned.

See Also
MMAC_OSD_SetRegionPixel
MMAC_OSD_Initialise

Sample Code
< tba >

21
MMAC_OSD_PlotPoints

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_PlotPoints(
MMAC_OSD_REGION regionID,
MMAC_OSD_POINT startPoint,
I16 numPoints,
UI8 *points,
MMAC_OSD_COLOUR *colour
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
StartPoint The first point in the sequence of points.
NumPoints The number of points in the sequence excluding the starting point.
Points Pointer to the list of points.
Colour The colour index or RGB table to use for the pixels.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_REGION
MMAC_OSD_INVALID_POSITION

Description
The function plots a number of contiguous points from the list of points provided in points, starting from
the point specified by startPoint. The array of points is encoded in Freeman encoding with a number
between ‘0’ and ‘7’ referencing the relative position of the pixel compared with the one just plotted. The
encoding is as follows:
-x x +x
-y 3 2 1
Y 4 X 0
+y 5 6 7

Where X indicates the position of the current pixel that has ‘8’ adjacent pixels the positions of which are
specified by the numbers 0~7.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned. If the startPoint is outside of the
region then MMAC_OSD_INVALID_POSITION will be returned.

22
See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

23
MMAC_OSD_FillRect

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_FillRect(
MMAC_OSD_REGION regionID,
MMAC_OSD_RECT *rect,
MMAC_OSD_COLOUR *colour
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Rect Rectangle defines the area to be filled.
Colour Colour index within palette or RGB table to fill area.
Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_INVALID_RECT
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_BLITTER_BUSY

Description
This function draws a filled rectangle within a region on the screen. The function
MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will be
returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the
value MMAC_OSD_INVALID_REGION will be returned. If the rectangle passed as rect is outside of
the region then MMAC_OSD_INVALID_RECT will be returned. If the function is called while the blitter is
busy then the return value MMAC_OSD_BLITTER_BUSY will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_FrameRect
MMAC_OSD_Initialise

Sample Code
< tba >

24
MMAC_OSD_FrameRect

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_FrameRect(
MMAC_OSD_REGION regionID,
MMAC_OSD_RECT *rect,
MMAC_OSD_COLOUR *colour,
UI16 penWidth
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Rect Rectangle defines the area to be drawn.
Colour Colour index within palette or RGB table to use for pen.
PenWidth Width of pen used to draw border.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_RECT
MMAC_OSD_INSUFFICIENT_MEMORY
MMAC_OSD_BLITTER_BUSY

Description
This function draws a frame rectangle with lines of width penWidth in colour colourIndex within the
region regionID on the screen. The function MMAC_OSD_Initialise() must be called first otherwise
MMAC_OSD_NOT_INITIALISED will be returned, followed by MMAC_OSD_CreateRegion() to obtain
a region handle regionID, otherwise the value MMAC_OSD_INVALID_REGION will be returned. If the
rectangle passed as rect is outside of the region then MMAC_OSD_INVALID_RECT will be returned. The
function temporarily allocates system memory to perform the blit, if the memory is exhausted then the
function will clean up, then return with MMAC_OSD_INSUFFICIENT_MEMORY. If the function is called
while the blitter is busy then the value MMAC_OSD_BLITTER_BUSY will be returned.

25
The value in penWidth is used to specify the number of pixels of width of each of the lines drawn inside
the bounding rectangle given by rect, as shown below:

Bounding rectangle rect

penWidth

See Also
MMAC_OSD_Initialise
MMAC_OSD_CreateRegion
MMAC_OSD_FillRect

Sample Code
< tba >

26
MMAC_OSD_CopyRect

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_CopyRect(
MMAC_OSD_REGION srcRegionID,
MMAC_OSD_RECT *rect,
MMAC_OSD_REGION destRegionID,
MMAC_OSD_POINT pointDest
)

Includes
#include “mmac/osd.h”

Inputs
SrcRegionID Pointer to defined region on screen containing source.
Rect Rectangle defines the rectangle to be copied.
DestRegionID Pointer to defined region on screen containing destination.
PointDest Point within region to copy rectangle to.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_INVALID_RECT
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_BLITTER_BUSY

Description
This function copies a rectangle defined by rect from the region srcRegionID and places it starting with
the top left corner at the point pointDest in region destRegionID, this may be the same region as the source
or another region in either OSD plane. The function MMAC_OSD_Initialise() must be called first
otherwise MMAC_OSD_NOT_INITIALISED will be returned, followed by
MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the value
MMAC_OSD_INVALID_REGION will be returned. If the rectangle passed as rect is outside of the region,
then MMAC_OSD_INVALID_RECT will be returned. If the function is called while the blitter is busy then
the value MMAC_OSD_BLITTER_BUSY will be returned.

See Also
MMAC_OSD_Initialise
MMAC_OSD_CreateRegion

Sample Code
< tba >

27
MMAC_OSD_SetRegionAlpha

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetRegionAlpha(
MMAC_OSD_REGION regionID,
UI8 alphaValue
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
AlphaValue New alpha value for region.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM

Description
Sets the Alpha Blending value for the Region
‘0’ = Alpha Blending OFF
‘1’ = Minimum visibility of OSD Region.
MMAC_OSD_MAX_ALPHA = Maximum visibility of OSD Region.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned. If alphaValue is out of the range
(0 – MMAC_OSD_MAX_ALPHA), then MMAC_OSD_INVALID_PARAM is returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_SetRegionClutTransparency
MMAC_OSD_Initialise

Sample Code
< tba >

28
MMAC_OSD_SetClutAlpha

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetClutAlpha(
MMAC_OSD_REGION regionID,
UI8 index,
MMAC_BOOL alphaState
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
index CLUT entry for switching the Alpha Blending ON/OFF.
AlphaState Switch for the Alpha Blending.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM

Description
Switches the Alpha Blending ON/OFF for a particular internal CLUT 256 entry, this corresponds to the
position in the RGB or YCbCr palette provided in MMAC_OSD_SetPalette(). In EMMA2, the alpha
value can only be applied individually to the colors in a CLUT of 1,2,4 or 8 bits per pixel. The function
MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED will be
returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID, otherwise the
value MMAC_OSD_INVALID_REGION will be returned. If index is greater than the number of colours in
the CLUT then MMAC_OSD_INVALID_PARAM is returned.

See Also
MMAC_OSD_SetRegionAlpha
MMAC_OSD_SetPalette
MMAC_OSD_Initialise

Sample Code
< tba >

29
MMAC_OSD_SetRegionClutTransparency

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetRegionClutTransparency(
MMAC_OSD_REGION regionID,
UI8 index,
UI8 transparencyValue
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Index CLUT entry for switching transparency.
TransparencyValue New transparency value for region.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM
MMAC_OSD_INVALID_PALETTE

Description
This function applies a transparency value to a region in the OSD plane. The internal CLUT entry is
overwritten and therefore not recoverable. The function MMAC_OSD_Initialise() must be called first
otherwise MMAC_OSD_NOT_INITIALISED will be returned, followed by MMAC_OSD_Create
Region() to obtain a region handle regionID, otherwise the value MMAC_OSD_INVALID_REGION will
be returned. If index is out of the range (‘0’ – MMAC_OSD_MAX_CLUT_ENTRY), or transparencyValue
is outside of the range (‘0’ – MMAC_OSD_MAX_TRANSPARENCY), then
MMAC_OSD_INVALID_PARAM is returned. A larger transparencyValue makes the region more
transparent. If the region does not have a palette defined then MMAC_OSD_INVALID_PALETTE will be
returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

30
MMAC_OSD_SetPalette

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetPalette(
MMAC_OSD_REGION regionID,
MMAC_OSD_PALETTE *palette
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
palette Pointer to palette array in RGB RGBQ or YCbCr.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_INVALID_PALETTE
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INSUFFICIENT_MEMORY

Description
This function accepts the palette information for the specified region and manipulates the data to place in
the internal CLUT. The information may be provided as an RGB, RGBQuad, palette or alternatively as
YCbCr colour space data. If the palette is too large for available memory then
MMAC_OSD_INSUFFICIENT_MEMORY will be returned. If the palette is incompatible with the region it
is being applied to e.g. incorrect colour depth, the value MMAC_OSD_INVALID_PALETTE will be
returned. The function MMAC_OSD_Initialise() must be called first otherwise
MMAC_OSD_NOT_INITIALISED will be returned, followed by MMAC_OSD_CreateRegion() to obtain
a region handle regionID, otherwise the value MMAC_OSD_INVALID_REGION will be returned.
It should be noted that this function specifies an entire new palette which overwrites any transparency
previously set up with MMAC_OSD_SetClutTransparency(), consequently the functions
MMAC_OSD_GetPaletteEntry() and MMAC_OSD_SetPaletteEntry() have been provided to save and
restore individual CLUT entries.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_SetRegionAlpha
MMAC_OSD_Initialise
MMAC_OSD_GetPaletteEntry
MMAC_OSD_SetPaletteEntry

Sample Code
< tba >

31
MMAC_OSD_SetPaletteEntry

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetPaletteEntry(
MMAC_OSD_REGION regionID,
UI16 index,
MMAC_OSD_CHROMA_ENTRY *paletteEntry
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Index Index in palette to set.
PaletteEntry Single palette entry in YCbCr.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PALETTE
MMAC_OSD_INVALID_PARAM

Description
This function accepts the single palette entry for the specified region and manipulates the data to place in
the internal CLUT in the place specified by index. The information may only be provided as YCbCr colour
space data. This function is particularly useful for restoring a palette entry after having previously used
MMAC_OSD_SetClutTransparency() which overwrites the internal CLUT entry.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned. If index is out of the range for the
region, or paletteEntry is invalid then MMAC_OSD_INVALID_PARAM is returned. If the region does not
have a palette defined then MMAC_OSD_INVALID_PALETTE will be returned.

See Also
MMAC_OSD_SetPalette
MMAC_OSD_SetClutTransparency
MMAC_OSD_Initialise
MMAC_OSD_GetPaletteEntry

Sample Code
< tba >

32
MMAC_OSD_GetPaletteEntry

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_GetPaletteEntry(
MMAC_OSD_REGION regionID,
UI16 index,
MMAC_OSD_CHROMA_ENTRY *paletteEntry
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Pointer to defined region on screen.
Index Index in palette to set.

Outputs
PaletteEntry Single palette entry in YCbCr.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PALETTE
MMAC_OSD_INVALID_PARAM

Description
This function returns the contents of a single palette entry specified by index in the specified region
regionID. The information will be returned as YCbCr colour space data. This function is particularly
useful for saving a palette entry prior to using MMAC_OSD_SetClutTransparency() which overwrites
the internal CLUT entry.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned. If index is out of the range for the
region, or paletteEntry is invalid then MMAC_OSD_INVALID_PARAM is returned. If the region does not
have a palette defined then MMAC_OSD_INVALID_PALETTE will be returned.

See Also
MMAC_OSD_SetPalette
MMAC_OSD_SetClutTransparency
MMAC_OSD_Initialise
MMAC_OSD_SetPaletteEntry

Sample Code
< tba >

33
MMAC_OSD_Reset

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_Reset(void)

Includes
#include “mmac/osd.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK

Description
This function resets the OSD subsystem.
It applies hardware reset to the OSD subsystem, resets the bit-blitter and deletes any regions.

See Also
MMAC_OSD_Initialise

Sample Code
< tba >

34
MMAC_OSD_SetTiling

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetTiling(
MMAC_OSD_REGION regionID,
MMAC_OSD_TILING_CONFIG *tilingConfig
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Defined region on screen.
TilingConfig Pointer to structure specifying the desired tiling configuration:
tileSize The size of the displayed tile.
enabled If MMAC_TRUE, tiling is currently enabled else it is disabled.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
This function sets size of the tiling and enable or disable of the tiling.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.

See Also
MMAC_OSD_GetTiling
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

35
MMAC_OSD_GetTiling

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetTiling(
MMAC_OSD_REGION regionID,
MMAC_OSD_TILING_CONFIG *tilingConfig
)

Includes
#include “mmac/osd.h”
Inputs
RegionID Defined region on screen.

Outputs
TilingConfig Pointer to structure int which the region's tiling configuration will be written:
TileSize The size of the displayed tile.
Enabled If MMAC_TRUE, tiling is enabled else it is disabled.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
The current tiling parameters of the specified region are returned in the structure pointed to by tilingConfig.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.

See Also
MMAC_OSD_SetTiling
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

36
MMAC_OSD_SetAlut

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetAlut(
MMAC_OSD_REGION regionID,
UI16 num,
UI8 *alutTable
)

Includes
#include “mmac/osd.h”

Inputs
regionID Defined region on screen.
num Number of redefining alpha value look up table (1 – 256).
alutTable Pointer to alpha look up table.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED

Description
This function accepts the ALUT information for the specified region and manipulates the data to place in
the internal ALUT.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.
If MMAC_OSD_ALUT_6 or MMAC_OSD_ALUT_8 is not specified in MMAC_OSD_CreateRegion(),
then MMAC_OSD_INVALID_ALUT will be returned.
On first define, if num != region then MMAC_OSD_INVALID_ALUT will be returned.
On second define, if num > region then MMAC_OSD_INVALID_ALUT will be returned.
On first define, if memory for alpha look up table is not available then
MMAC_OSD_INSUFFICIENT_MEMORY will be returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

37
MMAC_OSD_SetAlutEntry

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_SetAlutEntry(
MMAC_OSD_REGION regionID,
UI16 index,
UI8 alutValue
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Defined region on screen.
Index Index in ALUT to set (0-255).
AlutValue ALUT value.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM

Description
This function accepts the ALUT entry for the specified region and manipulates the data to place in the
internal ALUT in the place specified by index.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.
If alpha look up table is not defined in MMAC_OSD_SetAlut() then MMAC_OSD_INVALID_ALUT
will be returned.
If index >= region then MMAC_OSD_INVALID_ALUT will be returned.

See Also
MMAC_OSD_GetAlutEntry
MMAC_OSD_SetAlut
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

38
MMAC_OSD_GetAlutEntry

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_GetAlutEntry(
MMAC_OSD_REGION regionID,
UI16 index,
UI8 *alutValue
)

Includes
#include “mmac/osd.h”

Inputs
RegionID Defined region on screen.
Index Index in ALUT to get (0 – 255).

Outputs
AlutValue ALUT value.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM

Description
This function returns the contents of an ALUT entry specified by index in the specified region regionID.
The function MMAC_OSD_Initialise() must be called first otherwise MMAC_OSD_NOT_INITIALISED
will be returned, followed by MMAC_OSD_CreateRegion() to obtain a region handle regionID,
otherwise the value MMAC_OSD_INVALID_REGION will be returned.
If alpha look up table is not defined in MMAC_OSD_SetAlut() then MMAC_OSD_INVALID_ALUT
will be returned.
If index >= region then MMAC_OSD_INVALID_ALUT will be returned.

See Also
MMAC_OSD_SetAlutEntry
MMAC_OSD_SetAlut
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

39
MMAC_OSD_GetRegionInfo

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_GetRegionInfo(
MMAC_OSD_REGION regionID,
UI32 **topStartAddress,
UI32 **bottomStartAddress,
MMAC_OSD_RECT *rectSize,
UI8 *bitsPixel
)

Includes
#include “mmac/osd.h”

Inputs
regionID Defined region on screen.

Outputs
topStartAddress Physical start address of the OSD region top field.
bottomStartAddress Physical start address of the OSD region bottom field.
rectSize Size of the OSD region expressed as X, Y coordinates.
bitsPixel Number of bits per pixel of the OSD region.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_INVALID_REGION
MMAC_OSD_NOT_INITIALISED
MMAC_OSD_INVALID_PARAM

Description

This function returns information about the OSD region identified by regionID. The function returns the
physical start address of both top and bottom fields (or if non-interlaced, the frame start address is returned
in top StartAddress). The size of the region is returned as a set of X, Y coordinates in rectSize and the
number of bits per pixel returned in bitsPixel.

If MMAC_OSD_PARAMETER_CHECKING is define as MMAC_YES then the following checks are

carriedout:

If the OSD API is not initialised the MMAC_OSD_NOT_INITIALISED is returned. If the specified OSD
region,regionID does not represent a valid region then MMAC_OSD_INVALID_REGION is returned. If
either of the parameters topStartAddress,bottomStartAddress,rectSize or bitsPixel is NULL then
MMAC_OSD_INVALID_PARAM is returned.
See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

40
MMAC_OSD_AssociatePlane

Function Prototype
MMAC_OSD_RESULT_CODE MMAC_OSD_AssociatePlane(
MMAC_OSD_PLANE plane,
MMAC_OSD_HW_PLANE hwPlane
)

Includes
#include “mmac/osd.h”

Inputs
regionID Defined region on screen.

Outputs
topStartAddress Physical start address of the OSD region top field.
bottomStartAddress Physical start address of the OSD region bottom field.
rectSize Size of the OSD region expressed as X, Y coordinates.
bitsPixel Number of bits per pixel of the OSD region.

Event Notification
N/A

Return Codes
MMAC_OSD_OK
MMAC_OSD_NOT_INITIALISED

Description

This function associates a virtual plane to a physical hardware plane. The function is only available when
MMAC_OSD_VIRTUAL_PLANE is define as MMAC_YES. If MMAC_OSD_VIRTUAL_PLANE is define
as MMAC_YES, a plane which is specified when MMAC_OSD_CreateRegion is called is virtual plane
and the virtual plane should be associated to a physical hardware plane to display region on the plan.

If the OSD API is not initialised the MMAC_OSD_NOT_INITIALISED is returned.

See Also
MMAC_OSD_CreateRegion
MMAC_OSD_Initialise

Sample Code
< tba >

41
3 Data Structures

Includes

#include “mmac/osd.h”

MMAC_OSD_RESULT_CODE
Enumeration defining possible return codes for the osd functions.

typedef enum
{
MMAC_OSD_OK = 0,
MMAC_OSD_INSUFFICIENT_MEMORY,
MMAC_OSD_INVALID_REGION,
MMAC_OSD_INVALID_RECT,
MMAC_OSD_ALREADY_DISPLAYED,
MMAC_OSD_NOT_DISPLAYED,
MMAC_OSD_INVALID_PALETTE,
MMAC_OSD_NOT_INITIALISED,
MMAC_OSD_ALREADY_INITIALISED,
MMAC_OSD_INVALID_POSITION,
MMAC_OSD_INVALID_PARAM,
MMAC_OSD_BLITTER_BUSY,
MMAC_OSD_BLITTER_FAILED,
MMAC_OSD_INVALID_ALUT
} MMAC_OSD_RESULT_CODE;

MMAC_OSD_BltToRegion
Specifies the type of bitmap for the blit function.

typedef enum
{
MMAC_OSD_BITMAP,
MMAC_OSD_OTV_PIXMAP,
MMAC_OSD_CANAL_PIXMAP,
MMAC_OSD_RL2BPP
} MMAC_OSD_BITMAP_FORMAT;

General definitions

typedef void * MMAC_OSD_REGION;

typedef struct
{
UI16 x;
UI16 y;
} MMAC_OSD_POINT;

42
typedef enum
{
MMAC_OSD_BITSPIX1 = 0x01,
MMAC_OSD_BITSPIX2 = 0x02,
MMAC_OSD_BITSPIX4 = 0x04,
MMAC_OSD_BITSPIX8 = 0x08,
MMAC_OSD_RGB15= 0x0f, /* RGB15
(alpha_selection:R:G:B=1:5:5:5) mode */
MMAC_OSD_RGB16= 0x10, /* RGB16 (R:G:B=5:6:5) mode */
MMAC_OSD_RGB32= 0x20 /* RGB32 (alpha_value:R:G:B=8:8:8:8) mode
*/
} MMAC_OSD_BITSPIXEL;

typedef struct
{
UI16 left;
UI16 right;
UI16 top;
UI16 bottom;
} MMAC_OSD_RECT;

typedef enum
{
MMAC_OSD_CHROMA,
MMAC_OSD_RGB,
MMAC_OSD_RGB_QUAD
} MMAC_OSD_FORMAT;

#if (MMAC_OSD_VIRTUAL_PLANE == MMAC_YES)

typedef UI8 MMAC_OSD_PLANE;

typedef enum
{
MMAC_OSD_PLANE_ONE,
MMAC_OSD_PLANE_TWO
} MMAC_OSD_HW_PLANE;

#define MMAC_OSD_MAX_VIRTUAL_PLANE (256)

#else
typedef enum
{
MMAC_OSD_PLANE_ONE,
MMAC_OSD_PLANE_TWO
} MMAC_OSD_PLANE;
#endif

MMAC_OSD_SetPalette

typedef struct
{
UI8 y;
UI8 cb;
UI8 cr;
} MMAC_OSD_CHROMA_ENTRY;

typedef struct
{
UI8 red;
UI8 green;
UI8 blue;
} MMAC_OSD_RGB_ENTRY;

43
typedef struct
{
UI8 blue;
UI8 green;
UI8 red;
UI8 rgbReserved;
} MMAC_OSD_RGBQ_ENTRY;

In the following structure the paletteEntry should be cast to MMAC_OSD_RGB_ENTRY or

MMAC_OSD_CHROMA_ENTRY depending on which colour space is being used.

typedef struct
{
UI16 numEntries;
MMAC_OSD_FORMAT format;
void *paletteEntry;
} MMAC_OSD_PALETTE;

typedef struct
{
UI8 red;
UI8 green;
UI8 blue;
MMAC_BOOL alphaState;
} MMAC_OSD_RGB15_ENTRY;

typedef struct
{
UI8 red;
UI8 green;
UI8 blue;
} MMAC_OSD_RGB16_ENTRY;

typedef struct
{
UI8 red;
UI8 green;
UI8 blue;
UI8 alpha;
} MMAC_OSD_RGB32_ENTRY;

#define MMAC_OSD_MAX_ALPHA 255

#define MMAC_OSD_MAX_TRANSPARENCY 16
#define MMAC_OSD_MAX_CLUT_ENTRY 15
#define MMAC_OSD_MAX_CURSOR_ALPHA 255

Callback
The following type defines an MMAC_OSD_BITBLT_CALLBACK.

typedef void(*MMAC_OSD_BITBLT_CALLBACK)(void);

typedef enum
{
/* ALUT mode */
MMAC_OSD_ALUT_NONE = 0,
MMAC_OSD_ALUT_6 = 1, /* 6+1 bits */
MMAC_OSD_ALUT_8 = 2 /* 8+1 bits */
} MMAC_OSD_ALUT_MODE;

44
typedef enum
{
/* CLUT mode */
MMAC_OSD_CLUT_NONE = 0,
MMAC_OSD_CLUT_888,
MMAC_OSD_CLUT_644_X17COMPATIBLE, /* x17 compatible mode */
MMAC_OSD_CLUT_644_X17WITHEXCEPTION, /* x17 width exception mode */
MMAC_OSD_CLUT_644_X16, /* x16 mode */
MMAC_OSD_CLUT_644_X17_8 /* x17-8 mode */
} MMAC_OSD_CLUT_MODE;

typedef struct
{
UI16 width;
UI16 height;
MMAC_BOOL enabled;
} MMAC_OSD_TILING_CONFIG;
typedef union
{
UI8 colourIndex;
MMAC_OSD_RGB15_ENTRY rgb15Entry;
MMAC_OSD_RGB16_ENTRY rgb16Entry;
MMAC_OSD_RGB32_ENTRY rgb32Entry;
} MMAC_OSD_COLOUR;

45
4 Revision History
Title: API Specification: On Screen Display (OSD)
Ref: API_OSD.doc

Date Doc API Details of change Ref.

Ver Ver
0.01 Document created.
0.02 Initial Revision
0.03 Initial Revision
0.04 MMAC_OSD_ClutReloadEnable,
MMAC_OSD_ClutReloadDisable,
MMAC_OSD_AlutReloadEnable and
MMAC_OSD_AlutReloadDisable deleted.
MMAC_OSD_SetClutEntry and MMAC_OSD_GetAlutEntry
added.
0.05 Functions for true color were changed to xx_RGB function.
Function interface re-arranged.
0.06 xx_RGB() and xx_ext() is integrated into xx() functions.
parameter of plane is added in MMAC_OSD_SetMode()
MMAC_OSD_BlitSyncMode() is added.
MMAC_OSD_SetRegionTransparency() is renamed to
MMAC_OSD_SetRegionClutTransparency().
MMAC_OSD_SetPlanePriority()
MMAC_OSD_SetPlaneAlpha() and
MMAC_OSD_SetPlaneAlpha() is deleted.
0.07 MMAC_OSD_Display() is deleted
0.08 Fixed incorrect description in
MMAC_OSD_CreateRegion().
2002-08-06 0.09 Reformatted M-RI
2002-12-09 1.0 For release – same as v0.09 M-RI
2003-06-27 1.1 Doc number added. M-RJI
2004-02-10 1.11 Added MMAC_OSD_GetRegionInfo( ), M-HG
MMAC_OSD_AssociatePlane( ).
2004-02-11 1.2 Format check for issue. M-RJI

46