platform/inc/stbhwosd.h File Reference

Header file - Function prototypes for OSD control. More...

#include "osdtype.h"

Include dependency graph for stbhwosd.h:

Go to the source code of this file.

Typedefs
typedef enum e_blit_op	E_BLIT_OP
Enumerations
enum	e_blit_op { STB_BLIT_COPY, STB_BLIT_A_BLEND }
Functions
void	STB_OSDInitialise (U8BIT num_max_regions)
	Initialised the OSD hardware layer functions.
BOOLEAN	STB_OSDEnable (BOOLEAN enable)
	Enable/Disable the OSD.
BOOLEAN	STB_OSDDisableUIRegion (void)
	Disables (makes invisible) the OSD. This function needs to be implemented on platforms that cannot display the UI at the same time as subtitles or teletext.
BOOLEAN	STB_OSDEnableUIRegion (void)
	Disables (makes invisible) the OSD. This function needs to be implemented on platforms that cannot display the UI at the same time as subtitles or teletext.
void	STB_OSDSetTransparency (U8BIT trans)
	Sets the UI transparency level (0-100%)
U8BIT	STB_OSDGetTransparency (void)
	Returns the current UI transparency level.
void	STB_OSDSetPalette (U16BIT index, U16BIT num, U32BIT *trgb)
	Sets a range of palette entries to Trans/Red/Grn/Blue levels. This function is used for 8 bit colour depth only.
U32BIT *	STB_OSDGetCurrentPalette (void)
	Returns a pointer to the current TRGB palette (clut). This function is used for 8 bit colour depth only.
void	STB_OSDDrawBitmap (U16BIT x, U16BIT y, U16BIT width, U16BIT height, U8BIT bits, U8BIT *data)
	Draw a bitmap into the UI composition (invisible) buffer.
void	STB_OSDReadBitmap (U16BIT x, U16BIT y, U16BIT width, U16BIT height, U8BIT bits, U8BIT *data)
	Read a bitmap from the UI composition (invisible) buffer.
void	STB_OSDDrawPixel (U16BIT x, U16BIT y, U32BIT colour)
	Draw a single pixel in the UI composition buffer.
void	STB_OSDReadPixel (U16BIT x, U16BIT y, U32BIT *colour)
	Read a single pixel from the UI composition buffer.
void	STB_OSDDrawHLine (U16BIT x, U16BIT y, U16BIT width, U32BIT colour)
	Draw a horizontal line in the UI composition buffer.
void	STB_OSDDrawVLine (U16BIT x, U16BIT y, U16BIT height, U32BIT colour)
	Draw a vertical line in the UI composition buffer.
void	STB_OSDDrawRectangle (U16BIT x, U16BIT y, U16BIT width, U16BIT height, U32BIT colour, U8BIT thick, BOOLEAN fill)
	Draw a rectangle in the UI composition buffer.
void	STB_OSDClear (U32BIT colour)
	Clear the entire UI composition buffer to a single colour.
void	STB_OSDFill (U32BIT colour, E_BLIT_OP bflg)
	Clear the user interface layer to the given colour using the given blit op.
void	STB_OSDGetSize (U16BIT *width, U16BIT *height)
	Returns the current width and height of the OSD.
void	STB_OSDUpdate (void)
	Commit invisible UI buffer to visible surface and copy back.
void	STB_OSDRegisterRefreshHandler (void(*func)(void))
	Register app fn that can be used by the platform code OSD module to notify the application when the UI needs to be redrawn.
void	STB_OSDRegisterInUseCallback (U8BIT(*func)(void))
	App registered callback to indicate if OSD is in use.
void	STB_OSDRefreshDisplayCallback (void)
	Can be called by anyone to force redraw of the OSD by the UI. This function will cause the platform code OSD module to call the registered refresh handler (see STB_OSDRegisterRefreshHandler).
void	STB_OSDResize (BOOLEAN scaling, U16BIT width, U16BIT height, U16BIT x_offset, U16BIT y_offset)
	Reconifugres the OSD for a new screen size.
void	STB_OSDSetRegionDisplaySize (U16BIT width, U16BIT height)
	Should be called to set the size of the display so that SD subtitles can be scaled correctly for an HD display, or vice versa.
void *	STB_OSDCreateRegion (U16BIT width, U16BIT height, U8BIT depth)
	Creates a new OSD region (for subtitling)
void	STB_OSDDestroyRegion (void *handle)
	Destroys (free the resources used by) a region.
void	STB_OSDSetYCrCbPalette (void *region_handle, U32BIT *tycrcb)
	Sets a regions entire palette to a T,Y,CR,CB clut.
void	STB_OSDMoveRegion (void *handle, U16BIT x, U16BIT y)
	Move a region to new coordinates.
void	STB_OSDHideRegion (void *handle)
	Makes a region invisible.
void	STB_OSDShowRegion (void *handle)
	Makes a region visible.
void	STB_OSDDrawBitmapInRegion (void *handle, U16BIT x, U16BIT y, U16BIT w, U16BIT h, U8BIT *bitmap, BOOLEAN non_modifying_colour)
	Draw a bitmap in a specified region.
void	STB_OSDRegionToRegionCopy (void *handle_new, void *handle_orig)
	Copy a region to another region, including palette.
void	STB_OSDFillRegion (void *handle, U8BIT colour)
	Fill a region with a colour.
void	STB_OSDRegionFillRect (void *handle, U16BIT left, U16BIT top, U16BIT width, U16BIT height, U8BIT colour)
	Fill the rectangle within the given region with the given colour.
void	STB_OSDUpdateRegions (void)
	Updates the display of all subtitle regions.
void	STB_OSDSetRGBPalette (void *handle, U32BIT *trgb)
	Sets the RGB palette for the given region. This function is used for Teletext.
void	STB_OSDMhegSetPalette (U16BIT index, U16BIT number, const U32BIT *argb)
	Sets Colour Palette array of up to 256 values, for single byte colour depth. This palette being an array of 'U32BIT' (8 Alpha, 8 Red, 8 Green, 8 Blue).
void *	STB_OSDMhegSetResolution (U16BIT width, U16BIT height, U8BIT bits)
	Sets the size of the OSD to be used by MHEG engine. The return may be NULL, or pointer to valid Surface for the entire screen back-buffer. If it is the latter, then the Engine will draw to this surface using STB_OSDMhegBmpToSurf and STB_OSDMhegFillSurface, or by calling STB_OSDMhegLockBuffer to draw directly to buffer.
void *	STB_OSDMhegCreateSurface (U16BIT width, U16BIT height, BOOLEAN init, U32BIT colour)
	Creates a hardware surface on which MHEG5 engine will draw an individual MHEG object. At its basic the function can just allocate the buffer to be returned by STB_OSDMhegLockBuffer(). It's size being: (width * height * bytes_per_pixel) Also, when 'init' is TRUE, function initialises surface buffer to the specified colour. For pixel colour format of less than four bytes, use least significant bits of 'colour'.
void *	STB_OSDMhegLockBuffer (void *surface, U32BIT *pPitch)
	Converts hardware surface handle returned by STB_OSDMhegCreateSurface() to buffer address that the engine needs in order to draw the MHEG object. This function can inform HW that the engine needs write access to buffer. MHEG5 will use the return address and 'pitch' (or stride) value to locate pixel data. Before calling this function, 'pitch' is initialised to width as given by STB_OSDMhegCreateSurface(), but platform can alter this here.
void	STB_OSDMhegUnlockBuffer (void *surface)
	This function informs HW that MHEG5 is finished writing to the buffer.
void	STB_OSDMhegDestroySurface (void *surface)
	This function destroys surface and all data allocated by STB_OSDMhegCreateSurface()
void	STB_OSDMhegBlitBitmap (void *surface, S_RECTANGLE *pRect, U32BIT pitch, U16BIT screen_x, U16BIT screen_y, E_BLIT_OP bflg)
	Render bitmap on OSD back buffer in the given screen location, with given operation. The bitmap is referenced 'surface' - a handle returned by STB_OSDMhegCreateSurface() 1. It is a one-to-one mapping between surface pixels and screen pixels, so rect.width and rect.height give size of rectangle on the screen as well. 2. (rect.top + rect.height) is guarenteed to be less than or equal to height given to STB_OSDMhegCreateSurface()
void	STB_OSDMhegFillRectangle (S_RECTANGLE *pRect, U32BIT colour, E_BLIT_OP bflg)
	Draw a filled rectangle on OSD back buffer in the location given. Where pixel colour is less than four bytes, use least significant bits in 'colour'. 'rect' can be part of the screen or the entire screen.
void	STB_OSDMhegBlitStretch (S_RECTANGLE *pSrcRect, void *src_surf, S_RECTANGLE *pDstRect, void *dst_surf, U8BIT alpha_blend)
	Stretch blit bitmap data from source surface to destination surface using source and destination rectangles.
void	STB_OSDMhegFillSurface (void *surface, S_RECTANGLE *pRect, U32BIT colour, E_BLIT_OP bflg)
	Draw a filled rectangle on surface in the location given. Where pixel colour is less than four bytes, use least significant bits in 'colour'.
void	STB_OSDMhegUpdate (void)
	Commit OSD changes to the screen - changes given by previous calls to STB_OSDMhegDrawRectangle() and STB_OSDMhegDrawBitmap().
void	STB_OSDMhegClear (void)
	Clear MHEG's entire OSD.

---

Detailed Description

Header file - Function prototypes for OSD control.

Date:

06/02/2001

---

Function Documentation

void STB_OSDClear

(

U32BIT

colour

)

Clear the entire UI composition buffer to a single colour.

Parameters:

colour

colour to clear to

void* STB_OSDCreateRegion	(	U16BIT	width,
		U16BIT	height,
		U8BIT	depth
	)

Creates a new OSD region (for subtitling)

Parameters:

width	width of new region
height	height of new region
depth	bits per pixel of new region

Returns:

handle (pointer to) new region

void STB_OSDDestroyRegion

(

void *

handle

)

Destroys (free the resources used by) a region.

Parameters:

handle

handle of (pointer to) the region

BOOLEAN STB_OSDDisableUIRegion

(

void

)

Disables (makes invisible) the OSD. This function needs to be implemented on platforms that cannot display the UI at the same time as subtitles or teletext.

Returns:

TRUE if succesful, FALSE otherwise

void STB_OSDDrawBitmap	(	U16BIT	x,
		U16BIT	y,
		U16BIT	width,
		U16BIT	height,
		U8BIT	bits,
		U8BIT *	data
	)

Draw a bitmap into the UI composition (invisible) buffer.

Parameters:

x	the x coordinate where to draw
y	the x coordinate where to draw
width	width of bitmap in pixels
height	height of bitmap in pixels
bits	bits per pixel of source bitmap
data	the bitmap data

void STB_OSDDrawBitmapInRegion	(	void *	handle,
		U16BIT	x,
		U16BIT	y,
		U16BIT	w,
		U16BIT	h,
		U8BIT *	bitmap,
		BOOLEAN	non_modifying_colour
	)

Draw a bitmap in a specified region.

Parameters:

handle	handle of (pointer to) the region
x	x coordinate to draw bitmap
y	y coordinate to draw bitmap
w	width of bitmap
h	height of bitmap
bitmap	the bitmap data
non_modifying_colour	not used

void STB_OSDDrawHLine	(	U16BIT	x,
		U16BIT	y,
		U16BIT	width,
		U32BIT	colour
	)

Draw a horizontal line in the UI composition buffer.

Parameters:

x	x coordinate of line
y	y coordinate of line
width	width of line in pixels
colour	colour of line

void STB_OSDDrawPixel	(	U16BIT	x,
		U16BIT	y,
		U32BIT	colour
	)

Draw a single pixel in the UI composition buffer.

Parameters:

x	x coordinate of pixel
y	y coordinate of pixel
colour	colour of pixel

void STB_OSDDrawRectangle	(	U16BIT	x,
		U16BIT	y,
		U16BIT	width,
		U16BIT	height,
		U32BIT	colour,
		U8BIT	thick,
		BOOLEAN	fill
	)

Draw a rectangle in the UI composition buffer.

Parameters:

x	x coordinate of rectangle
y	x coordinate of rectangle
width	width of rectangle
height	height of rectangle
colour	colour of rectangle
thick	thickness of outline for hollow rectangles
fill	TRUE for solid (filled) rectangle

void STB_OSDDrawVLine	(	U16BIT	x,
		U16BIT	y,
		U16BIT	height,
		U32BIT	colour
	)

Draw a vertical line in the UI composition buffer.

Parameters:

x	x coordinate of line
y	y coordinate of line
height	height of line in pixels
colour	colour of line

BOOLEAN STB_OSDEnable

(

BOOLEAN

enable

)

Enable/Disable the OSD.

Parameters:

enable

TRUE to enable

Returns:

The new state ( i.e. will = param if successful )

BOOLEAN STB_OSDEnableUIRegion

(

void

)

Disables (makes invisible) the OSD. This function needs to be implemented on platforms that cannot display the UI at the same time as subtitles or teletext.

Returns:

TRUE if succesful, FALSE otherwise

void STB_OSDFill	(	U32BIT	colour,
		E_BLIT_OP	bflg
	)

Clear the user interface layer to the given colour using the given blit op.

Parameters:

colour	colour to clear to
bflg	blit operation

void STB_OSDFillRegion	(	void *	handle,
		U8BIT	colour
	)

Fill a region with a colour.

Parameters:

handle	handle of (pointer to) the region
colour	the colour index to fill with

U32BIT* STB_OSDGetCurrentPalette

(

void

)

Returns a pointer to the current TRGB palette (clut). This function is used for 8 bit colour depth only.

Returns:

Pointer to an array of 32bit trans,red,green,blue values

void STB_OSDGetSize	(	U16BIT *	width,
		U16BIT *	height
	)

Returns the current width and height of the OSD.

Parameters:

width	width of OSD in pixels
height	height of OSD in pixels

U8BIT STB_OSDGetTransparency

(

void

)

Returns the current UI transparency level.

Returns:

The current transparency in percent

void STB_OSDHideRegion

(

void *

handle

)

Makes a region invisible.

Parameters:

handle

handle of (pointer to) the region

void STB_OSDInitialise

(

U8BIT

num_max_regions

)

Initialised the OSD hardware layer functions.

Parameters:

num_max_regions

number of regions required (not used here)

void STB_OSDMhegBlitBitmap	(	void *	surface,
		S_RECTANGLE *	pRect,
		U32BIT	pitch,
		U16BIT	screen_x,
		U16BIT	screen_y,
		E_BLIT_OP	bflg
	)

Render bitmap on OSD back buffer in the given screen location, with given operation. The bitmap is referenced 'surface' - a handle returned by STB_OSDMhegCreateSurface() 1. It is a one-to-one mapping between surface pixels and screen pixels, so rect.width and rect.height give size of rectangle on the screen as well. 2. (rect.top + rect.height) is guarenteed to be less than or equal to height given to STB_OSDMhegCreateSurface()

Parameters:

surface	Handle of surface returned by STB_OSDMhegCreateSurface
rect	source rectangle within surface - top/left is offset into bitmap referenced by 'surface', width/height gives size.
pitch	Width of line of source bitmap data - as returned by STB_OSDMhegLockBuffer()
screen_x	Left or X position on screen to draw bitmap
screen_y	Top or Y position on screen to draw bitmap
bflg	Operation - COPY or ALPHA BLEND

Returns:

void

void STB_OSDMhegBlitStretch	(	S_RECTANGLE *	pSrcRect,
		void *	src_surf,
		S_RECTANGLE *	pDstRect,
		void *	dst_surf,
		U8BIT	alpha_blend
	)

Stretch blit bitmap data from source surface to destination surface using source and destination rectangles.

Parameters:

pSrcRect	rectangle for bitmap data
src_surf	handle returned by STB_OSDMhegCreateSurface
pDstRect	rectangle for destination on surface
dst_surf	handle returned by STB_OSDMhegCreateSurface
alpha_blend	Operation - COPY or ALPHA BLEND (zero or 0xff)

Returns:

void

void* STB_OSDMhegCreateSurface	(	U16BIT	width,
		U16BIT	height,
		BOOLEAN	init,
		U32BIT	colour
	)

Creates a hardware surface on which MHEG5 engine will draw an individual MHEG object. At its basic the function can just allocate the buffer to be returned by STB_OSDMhegLockBuffer(). It's size being: (width * height * bytes_per_pixel) Also, when 'init' is TRUE, function initialises surface buffer to the specified colour. For pixel colour format of less than four bytes, use least significant bits of 'colour'.

Parameters:

width	Width of requested surface in pixels
height	Height of requested surface in pixels
init	If TRUE, initialise buffer with colour.
colour	colour for all pixels in buffer.

Returns:

void* Success - Handle to surface. Failure - NULL (or zero)

void STB_OSDMhegDestroySurface

(

void *

surface

)

This function destroys surface and all data allocated by STB_OSDMhegCreateSurface()

Parameters:

surface

Handle of surface returned by STB_OSDMhegCreateSurface

Returns:

void

void STB_OSDMhegFillRectangle	(	S_RECTANGLE *	pRect,
		U32BIT	colour,
		E_BLIT_OP	bflg
	)

Draw a filled rectangle on OSD back buffer in the location given. Where pixel colour is less than four bytes, use least significant bits in 'colour'. 'rect' can be part of the screen or the entire screen.

Parameters:

rect	rectangle on screen - with top,left starting position
colour	colour for all pixels in rectangle.
bflg	Operation - COPY or ALPHA BLEND

Returns:

void

void STB_OSDMhegFillSurface	(	void *	surface,
		S_RECTANGLE *	pRect,
		U32BIT	colour,
		E_BLIT_OP	bflg
	)

Draw a filled rectangle on surface in the location given. Where pixel colour is less than four bytes, use least significant bits in 'colour'.

Parameters:

surface	handle returned by STB_OSDMhegCreateSurface
rect	rectangle on screen - with top,left starting position
colour	colour for all pixels in rectangle.
bflg	Operation - COPY or ALPHA BLEND

Returns:

void

void* STB_OSDMhegLockBuffer	(	void *	surface,
		U32BIT *	pPitch
	)

Converts hardware surface handle returned by STB_OSDMhegCreateSurface() to buffer address that the engine needs in order to draw the MHEG object. This function can inform HW that the engine needs write access to buffer. MHEG5 will use the return address and 'pitch' (or stride) value to locate pixel data. Before calling this function, 'pitch' is initialised to width as given by STB_OSDMhegCreateSurface(), but platform can alter this here.

Parameters:

surface	Handle of surface returned by STB_OSDMhegCreateSurface
pitch	width in bytes of one line of pixel data in buffer

Returns:

void* Address of the buffer

void STB_OSDMhegSetPalette	(	U16BIT	index,
		U16BIT	number,
		const U32BIT *	argb
	)

Sets Colour Palette array of up to 256 values, for single byte colour depth. This palette being an array of 'U32BIT' (8 Alpha, 8 Red, 8 Green, 8 Blue).

Parameters:

index
number	Size of palette array
argb	pointer to palette array

void* STB_OSDMhegSetResolution	(	U16BIT	width,
		U16BIT	height,
		U8BIT	bits
	)

Sets the size of the OSD to be used by MHEG engine. The return may be NULL, or pointer to valid Surface for the entire screen back-buffer. If it is the latter, then the Engine will draw to this surface using STB_OSDMhegBmpToSurf and STB_OSDMhegFillSurface, or by calling STB_OSDMhegLockBuffer to draw directly to buffer.

Parameters:

width	Width of MHEG OSD resolution
height	Height of MHEG OSD resolution
bits	Number of bits per pixel

void STB_OSDMhegUnlockBuffer

(

void *

surface

)

This function informs HW that MHEG5 is finished writing to the buffer.

Parameters:

surface

Handle of surface returned by STB_OSDMhegCreateSurface

Returns:

void

void STB_OSDMhegUpdate

(

void

)

Commit OSD changes to the screen - changes given by previous calls to STB_OSDMhegDrawRectangle() and STB_OSDMhegDrawBitmap().

Returns:

void

void STB_OSDMoveRegion	(	void *	handle,
		U16BIT	x,
		U16BIT	y
	)

Move a region to new coordinates.

Parameters:

handle	handle of (pointer to) the region
x	new x coordinate of region
y	new y coordinate of region

void STB_OSDReadBitmap	(	U16BIT	x,
		U16BIT	y,
		U16BIT	width,
		U16BIT	height,
		U8BIT	bits,
		U8BIT *	data
	)

Read a bitmap from the UI composition (invisible) buffer.

Parameters:

x	the x coordinate where to read
y	the x coordinate where to read
width	width of bitmap in pixels
height	height of bitmap in pixels
bits	bits per pixel of destination bitmap
data	the resultant bitmap data

void STB_OSDReadPixel	(	U16BIT	x,
		U16BIT	y,
		U32BIT *	colour
	)

Read a single pixel from the UI composition buffer.

Parameters:

x	x coordinate of pixel
y	y coordinate of pixel
colour	colour of pixel

void STB_OSDRegionFillRect	(	void *	handle,
		U16BIT	left,
		U16BIT	top,
		U16BIT	width,
		U16BIT	height,
		U8BIT	colour
	)

Fill the rectangle within the given region with the given colour.

Parameters:

handle	- region handle
left	- x position of rectangle within the region
top	- y position of rectangle within the region
width	- rectangle width
height	rectangle height
colour	- fill colour

void STB_OSDRegionToRegionCopy	(	void *	handle_new,
		void *	handle_orig
	)

Copy a region to another region, including palette.

Parameters:

handle_new	handle of (pointer to) new (destination) region
handle_old	handle of (pointer to) old (source) region

void STB_OSDRegisterInUseCallback

(

U8BIT(*)(void)

func

)

App registered callback to indicate if OSD is in use.

Parameters:

func	the callback function

void STB_OSDRegisterRefreshHandler

(

void(*)(void)

func

)

Register app fn that can be used by the platform code OSD module to notify the application when the UI needs to be redrawn.

Parameters:

func	the callback function

void STB_OSDResize	(	BOOLEAN	scaling,
		U16BIT	width,
		U16BIT	height,
		U16BIT	x_offset,
		U16BIT	y_offset
	)

Reconifugres the OSD for a new screen size.

Parameters:

scaling	TRUE if osd scaling is required due to MHEG scene aspect ratio, FALSE otherwise
width	width of OSD in pixels
height	height of OSD in pixels
x_offset	offset of OSD from left of screen, in pixels
y_offset	offset of OSD from top of screen, in pixels

void STB_OSDSetPalette	(	U16BIT	index,
		U16BIT	num,
		U32BIT *	trgb
	)

Sets a range of palette entries to Trans/Red/Grn/Blue levels. This function is used for 8 bit colour depth only.

Parameters:

index	starting number of palette entry to be set
num	number of consecutive palette entries to set
trgb	the colour value array

void STB_OSDSetRegionDisplaySize	(	U16BIT	width,
		U16BIT	height
	)

Should be called to set the size of the display so that SD subtitles can be scaled correctly for an HD display, or vice versa.

Parameters:

width	- display width defined by the subtitle DDS
height	- display height defined by the subtitle DDS

void STB_OSDSetRGBPalette	(	void *	handle,
		U32BIT *	trgb
	)

Sets the RGB palette for the given region. This function is used for Teletext.

Parameters:

handle	region handle as returned by STB_OSDCreateRegion.
trgb	pointer to the palette array

void STB_OSDSetTransparency

(

U8BIT

trans

)

Sets the UI transparency level (0-100%)

Parameters:

trans

transparency in percent

void STB_OSDSetYCrCbPalette	(	void *	region_handle,
		U32BIT *	tycrcb
	)

Sets a regions entire palette to a T,Y,CR,CB clut.

Parameters:

handle	handle (pointer to) the region to configure
tycrcb	pointer to the CLUT entries

void STB_OSDShowRegion

(

void *

handle

)

Makes a region visible.

Parameters:

handle

handle of (pointer to) the region