include/stb_osd.h File Reference

Graphics functions required by the HD MHEG5 engine. All references to colour used in these functions can be one of three formats: * 8-bit colour palette * 16-bit ARGB (4-4-4-4) * 32-bit ARGB (8-8-8-8) The MHEG engine will use the format indicated in MHEG5_Open() More...

#include "techtype.h"
#include "osdtype.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_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

Graphics functions required by the HD MHEG5 engine. All references to colour used in these functions can be one of three formats: * 8-bit colour palette * 16-bit ARGB (4-4-4-4) * 32-bit ARGB (8-8-8-8) The MHEG engine will use the format indicated in MHEG5_Open()

Date:

30/04/2008

Author:

Adam Sturtridge

---

Function Documentation

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