mpeghUIManager.h File Reference

MPEG-H UI Manager library interface header file. More...

#include "mpeghexport.h"

Go to the source code of this file.

Macros
#define	MAX_NUMBER_SECONDARY_STREAMS   16
#define	MPEGH_UI_FORCE_UPDATE   1
	Input flag for mpegh_UI_GetXmlSceneState(): Force output of XML description, even if nothing has changed since the last call.
#define	MPEGH_UI_FORCE_RESTART_XML   4
	Input flag for mpegh_UI_GetXmlSceneState(): Force restart of XML output if incomplete output was returned by previous call.
#define	MPEGH_UI_NO_CHANGE   1
	Flag returned by mpegh_UI_GetXmlSceneState(): Nothing has changed since the last call, no XML output was generated.
#define	MPEGH_UI_CONTINUES_XML   2
	Flag returned by mpegh_UI_GetXmlSceneState(): XML output is a continuation of incomplete output of the previous call.
#define	MPEGH_UI_INCOMPLETE_XML   4
	Flag returned by mpegh_UI_GetXmlSceneState(): XML output is not complete, at least one further call of the function is required to get the complete XML output.
#define	MPEGH_UI_SHORT_OUTPUT   8
	Flag returned by mpegh_UI_GetXmlSceneState(): only minimal XML output was generated, a further call of the function will return the full XML scene description.

Typedefs
typedef struct MPEGH_UI_MANAGER *	HANDLE_MPEGH_UI_MANAGER

Enumerations
enum	MPEGH_UI_ERROR {   MPEGH_UI_OK = 0, MPEGH_UI_OUT_OF_MEMORY, MPEGH_UI_BUFFER_TOO_SMALL, MPEGH_UI_INVALID_PARAM,   MPEGH_UI_NOT_ALLOWED, MPEGH_UI_INVALID_STATE, MPEGH_UI_PARSE_ERROR, MPEGH_UI_OK_BUT_NO_VALID_DATA }

Functions
MPEGHDEC_EXPORT HANDLE_MPEGH_UI_MANAGER	mpegh_UI_Manager_Open (void)
	Open a mpegh UI manager instance. More...
MPEGHDEC_EXPORT void	mpegh_UI_Manager_Close (HANDLE_MPEGH_UI_MANAGER self)
	De-allocate all resources of a mpegh UI manager instance. More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_GetXmlSceneState (HANDLE_MPEGH_UI_MANAGER self, char *xmlOut, unsigned int xmlOutSize, unsigned int flagsIn, unsigned int *flagsOut)
	Get XML description of audio scene and available user interactivity parameters. More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_ApplyXmlAction (HANDLE_MPEGH_UI_MANAGER self, const char *xmlIn, unsigned int xmlInSize, unsigned int *flagsOut)
	Send XML description of UI command to the UI manager. More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_FeedMHAS (HANDLE_MPEGH_UI_MANAGER self, unsigned char *mhasBuffer, unsigned int mhasLength)
	Feed MHAS input into UI manager. More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_UpdateMHAS (HANDLE_MPEGH_UI_MANAGER self, unsigned char *mhasBuffer, unsigned int mhasBufferLength, unsigned int *mhasLength)
	Update MHAS buffer, inserting UI and DRC packets from UI manager. A previous call of mpegh_UI_FeedMHAS() is required. More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_SetPersistenceMemory (HANDLE_MPEGH_UI_MANAGER self, void *persistenceMemoryBlock, unsigned short persistenceMemorySize)
	Set memory block for storing UI persistency data (activates internal persistence handling) More...
MPEGHDEC_EXPORT MPEGH_UI_ERROR	mpegh_UI_GetPersistenceMemory (HANDLE_MPEGH_UI_MANAGER self, void **persistenceMemoryBlock, unsigned short *persistenceMemorySize)
	Get current UI persistency memory block (updates content, call is required before storing persistence memory for later reuse!) More...

Detailed Description

MPEG-H UI Manager library interface header file.

Definition in file mpeghUIManager.h.

Function Documentation

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_ApplyXmlAction	(	HANDLE_MPEGH_UI_MANAGER	self,
		const char *	xmlIn,
		unsigned int	xmlInSize,
		unsigned int *	flagsOut
	)

Send XML description of UI command to the UI manager.

Parameters

[in]	self	UI manager handle.
[in]	xmlIn	Pointer to a buffer containing the XML command string.
[in]	xmlInSize	Size of the XML string (number of chars).
[out]	flagsOut	Pointer to bit field with flags returned by the UI manager, currently not used.

Returns

Error code.

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_FeedMHAS	(	HANDLE_MPEGH_UI_MANAGER	self,
		unsigned char *	mhasBuffer,
		unsigned int	mhasLength
	)

Feed MHAS input into UI manager.

Parameters

[in]	self	UI manager handle.
[in]	mhasBuffer	Input buffer containing all MHAS packets for exactly one audio frame.
[in]	mhasLength	Size of MHAS packets in bytes.

Returns

Error code.

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_GetPersistenceMemory	(	HANDLE_MPEGH_UI_MANAGER	self,
		void **	persistenceMemoryBlock,
		unsigned short *	persistenceMemorySize
	)

Get current UI persistency memory block (updates content, call is required before storing persistence memory for later reuse!)

Parameters

[in]	self	UI manager handle.
[in,out]	persistenceMemoryBlock	Pointer to a pointer receiving the address of the currently active memory block used by the UI manager for saving persistency data. After the call the content of the memory block is ready for storing it for late reuse. A NULL pointer is returned if internal persistency handling has not been activated.
[out]	persistenceMemorySize	Pointer to a variable receiving the size of the current memory block in bytes.

Returns

Error code.

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_GetXmlSceneState	(	HANDLE_MPEGH_UI_MANAGER	self,
		char *	xmlOut,
		unsigned int	xmlOutSize,
		unsigned int	flagsIn,
		unsigned int *	flagsOut
	)

Get XML description of audio scene and available user interactivity parameters.

Parameters

[in]	self	UI manager handle.
[out]	xmlOut	Pointer to external output buffer where the XML string will be stored.
[in]	xmlOutSize	Size of the output buffer (number of chars). Has to be at least 1024 to ensure success of the function.
[in]	flagsIn	Bit field with flags for the UI manager: (flags & MPEGH_UI_FORCE_UPDATE) != 0: Force output of XML description even if nothing has changed (flags & MPEGH_UI_FORCE_RESTART_XML) != 0: Restart XML output from the beginning (if incomplete output was returned by previous call).
[out]	flagsOut	Pointer to bit field with flags returned by the UI manager: (flags & MPEGH_UI_NO_CHANGE) != 0: Nothing has changed since the previous call of this function, no XML output was written. (flags & MPEGH_UI_CONTINUES_XML) != 0: The XML output is a continuation of incomplete output of the previous call and has to be appended to the output of the previous call. (flags & MPEGH_UI_INCOMPLETE_XML) != 0: The XML output is not yet complete, at least one further call of the function is required to get the remaining part.

Returns

Error code.

MPEGHDEC_EXPORT void mpegh_UI_Manager_Close

(

HANDLE_MPEGH_UI_MANAGER

self

)

De-allocate all resources of a mpegh UI manager instance.

Parameters

[in,out]

self

UI manager handle.

Returns

void

MPEGHDEC_EXPORT HANDLE_MPEGH_UI_MANAGER mpegh_UI_Manager_Open

(

void

)

Open a mpegh UI manager instance.

Returns

UI manager handle

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_SetPersistenceMemory	(	HANDLE_MPEGH_UI_MANAGER	self,
		void *	persistenceMemoryBlock,
		unsigned short	persistenceMemorySize
	)

Set memory block for storing UI persistency data (activates internal persistence handling)

Parameters

[in]	self	UI manager handle.
[in]	persistenceMemoryBlock	Pointer to memory block used by UI manager for saving persistency data. The caller is responsible for allocating the memory. The start address of the memory block has to be 16 bit aligned (i.e. a multiple of 2), otherwise the function fails and returns an error. The memory block must not be modified or deallocated before the UI manager is closed or a different memory block is set by a further call of this function. The memory block can be empty or filled with saved content of a previous session. If the content of the memory block is saved for later use, a call of mpegh_UI_GetPersistenceMemory() is required directly before saving the data. This parameter can be NULL for deactivating internal persistency handling.
[in]	persistenceMemorySize	Size of the memory block in bytes. The minimum recommended size is 512 bytes. If the size is too small, the function fails and returns an error.

Returns

Error code.

MPEGHDEC_EXPORT MPEGH_UI_ERROR mpegh_UI_UpdateMHAS	(	HANDLE_MPEGH_UI_MANAGER	self,
		unsigned char *	mhasBuffer,
		unsigned int	mhasBufferLength,
		unsigned int *	mhasLength
	)

Update MHAS buffer, inserting UI and DRC packets from UI manager. A previous call of mpegh_UI_FeedMHAS() is required.

Parameters

[in]	self	UI manager handle.
[in,out]	mhasBuffer	Input/output buffer, modified in-place. As input has to contain exactly the same data as passed to previous call of mpegh_UI_FeedMHAS(). Upon return the buffer is updated with UI and DRC packets inserted.
[in]	mhasBufferLength	Size of buffer in bytes. This should be at least the size of the input MHAS data plus 256 bytes.
[in,out]	mhasLength	Pointer to variable receiving total size of updated MHAS packet buffer in bytes.

Returns

Error code.