Speech decoder codec interface

Defines
#define	SPHDEC1_EOK   ISPHDEC1_EOK
#define	SPHDEC1_EFAIL   ISPHDEC1_EFAIL
#define	SPHDEC1_EUNSUPPORTED   ISPHDEC1_EUNSUPPORTED
#define	SPHDEC1_ETIMEOUT   VISA_ETIMEOUT
#define	SPHDEC1_FOREVER   VISA_FOREVER
Typedefs
typedef VISA_Handle	SPHDEC1_Handle
	Opaque handle to a SPHDEC1 codec.
typedef ISPHDEC1_Params	SPHDEC1_Params
typedef ISPHDEC1_InArgs	SPHDEC1_InArgs
typedef ISPHDEC1_OutArgs	SPHDEC1_OutArgs
typedef ISPHDEC1_Cmd	SPHDEC1_Cmd
typedef ISPHDEC1_DynamicParams	SPHDEC1_DynamicParams
typedef ISPHDEC1_Status	SPHDEC1_Status
Functions
Int32	SPHDEC1_control (SPHDEC1_Handle handle, SPHDEC1_Cmd id, SPHDEC1_DynamicParams *params, SPHDEC1_Status *status)
	Execute the control() method in this instance of a speech decoder algorithm.
SPHDEC1_Handle	SPHDEC1_create (Engine_Handle e, String name, SPHDEC1_Params *params)
	Create an instance of a speech decoder algorithm.
Void	SPHDEC1_delete (SPHDEC1_Handle handle)
	Delete the instance of a speech decoder algorithm.
Int32	SPHDEC1_process (SPHDEC1_Handle handle, XDM1_SingleBufDesc *inBuf, XDM1_SingleBufDesc *outBuf, SPHDEC1_InArgs *inArgs, SPHDEC1_OutArgs *outArgs)
	Execute the process() method in this instance of a speech decoder algorithm.
XDAS_Int32	SPHDEC1_processAsync (SPHDEC1_Handle handle, XDM1_SingleBufDesc *inBuf, XDM1_SingleBufDesc *outBuf, SPHDEC1_InArgs *inArgs, SPHDEC1_OutArgs *outArgs)
	Perform asynchronous submission to this instance of a speech decoder algorithm.
XDAS_Int32	SPHDEC1_processWait (SPHDEC1_Handle handle, XDM1_SingleBufDesc *inBuf, XDM1_SingleBufDesc *outBuf, SPHDEC1_InArgs *inArgs, SPHDEC1_OutArgs *outArgs, UInt timeout)
	Wait for a return message from a previous invocation of SPHDEC1_processAsync() in this instance of an speech decoder algorithm.

---

Detailed Description

This is the SPHDEC1 speech decoder codec interface. Several of the data types in this API are specified by the XDM interface; please see the XDM documentation for those details.

---

Define Documentation

#define SPHDEC1_EOK   ISPHDEC1_EOK

Success.

#define SPHDEC1_EFAIL   ISPHDEC1_EFAIL

General failure.

#define SPHDEC1_EUNSUPPORTED   ISPHDEC1_EUNSUPPORTED

Request is unsupported.

#define SPHDEC1_ETIMEOUT   VISA_ETIMEOUT

Timeout occurred.

#define SPHDEC1_FOREVER   VISA_FOREVER

Special value for timeout parameter indicating never timeout.

---

Typedef Documentation

typedef VISA_Handle SPHDEC1_Handle

Opaque handle to a SPHDEC1 codec.

typedef ISPHDEC1_Params SPHDEC1_Params

Defines the creation time parameters for all ISPHDEC1 instance objects.

Remarks:

Some of the fields in this structure are optional and depend on the class of speech decoder you're creating.

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

typedef ISPHDEC1_InArgs SPHDEC1_InArgs

Defines the input arguments for all ISPHDEC1 instance process function.

typedef ISPHDEC1_OutArgs SPHDEC1_OutArgs

Defines the run time output arguments for all ISPHDEC1 instance objects.

Remarks:

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

ISPHDEC1_Fxns::process()

Defines the control commands for the ISPHDEC1 module.

Remarks:

This ID can be extended in IMOD interface for additional control commands.

See also:

XDM_CmdId

ISPHDEC1_Fxns::control()

typedef ISPHDEC1_Cmd SPHDEC1_Cmd

typedef ISPHDEC1_DynamicParams SPHDEC1_DynamicParams

This structure defines the codec parameters that can be modified after creation via ISPHDEC1_Fxns.control().

Remarks:

It is not necessary that a given implementation support all dynamic parameters to be configurable at run time. If a particular algorithm does not support run-time updates to a parameter that the application is attempting to change at runtime, it may indicate this as an error.

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

ISPHDEC1_Fxns::control()

Defines instance status parameters.

Remarks:

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

ISPHDEC1_Fxns::control()

typedef ISPHDEC1_Status SPHDEC1_Status

---

Function Documentation

Int32 SPHDEC1_control	(	SPHDEC1_Handle	handle,
		SPHDEC1_Cmd	id,
		SPHDEC1_DynamicParams *	params,
		SPHDEC1_Status *	status
	)

Execute the control() method in this instance of a speech decoder algorithm.

Parameters:

[in]	handle	Handle to a created speech decoder instance.
[in]	id	Command id for XDM control operation.
[in]	params	Runtime control parameters used for decoding.
[out]	status	Status info upon completion of decode operation.

Precondition:

handle is a valid (non-NULL) speech decoder handle and the speech decoder is in the created state.

Return values:

	SPHDEC1_EOK	Success.
	SPHDEC1_EFAIL	Failure.
	SPHDEC1_EUNSUPPORTED	Unsupported request.

Remarks:

This is a blocking call, and will return after the control command has been executed.

See also:

SPHDEC1_create()

SPHDEC1_delete()

ISPHDEC1_Fxns()control()

SPHDEC1_Handle SPHDEC1_create	(	Engine_Handle	e,
		String	name,
		SPHDEC1_Params *	params
	)

Create an instance of a speech decoder algorithm.

Instance handles must not be concurrently accessed by multiple threads; each thread must either obtain its own handle (via SPHDEC1_create()) or explicitly serialize access to a shared handle.

Parameters:

[in]	e	Handle to an opened engine.
[in]	name	String identifier of the type of speech decoder to create.
[in]	params	Creation parameters.

Return values:

	NULL	An error has occurred.
	non-NULL	The handle to the newly created speech decoder instance.

Remarks:

params is optional. If it's not supplied, codec-specific default params will be used.

Depending on the configuration of the engine opened, this call may create a local or remote instance of the speech1 decoder.

In general, name is the name of the codec configured by the system integrator. However, an optional "argument string" may be appended to the codec name, to allow the codec's configured priority and/or the heaps where its memory will be allocated and/or the number of VISA messages to allocate, to be overridden. This optional argument string is of the form ":priority:flag:number-of-messages", and can be specified with an empty field for any element that you don't want to be overridden, e.g. "mp3:::3" to cause 3 messages to be allocated while using the default values for priority and the heap flag.

priority is the new priority to create the codec with.

The flag must be either 0 or 1, and if 1, all memory allocated for the codec will be in the heap that corresponds to IALG_EXTERNAL. If flag is 0, the memory for the codec will be allocated from the heaps it has requested. For example, if a codec named "mp3" has been configured into the system, setting name to "mp3:4" would cause the codec to be created at priority 4, instead of whatever priority was configured. This feature is useful if more than one instance of the codec are to be created at different priorities.

The flag can be used to prevent the codec from using any internal memory, for example, if it is to be run at the same time as another codec that must use internal memory, and there is insufficient internal memory for both.

The number-of-messages overrides the default of 1 message, and is useful (or required, practically speaking) for when the "asynchronous" process method is used, i.e. "AUDENC1_processAsync()"

See also:

Engine_open()

SPHDEC1_delete()

Void SPHDEC1_delete

(

SPHDEC1_Handle

handle

)

Delete the instance of a speech decoder algorithm.

Parameters:

[in]

handle

Handle to a created speech decoder instance.

Remarks:

Depending on the configuration of the engine opened, this call may delete a local or remote instance of the speech decoder.

Precondition:

handle is a valid (non-NULL) handle which is in the created state.

Postcondition:

All resources allocated as part of the SPHDEC1_create() operation (memory, DMA channels, etc.) are freed.

See also:

SPHDEC1_create()

Int32 SPHDEC1_process	(	SPHDEC1_Handle	handle,
		XDM1_SingleBufDesc *	inBuf,
		XDM1_SingleBufDesc *	outBuf,
		SPHDEC1_InArgs *	inArgs,
		SPHDEC1_OutArgs *	outArgs
	)

Execute the process() method in this instance of a speech decoder algorithm.

Parameters:

[in]	handle	Handle to a created speech decoder instance.
[in]	inBuf	A buffer descriptor containing an input buffer.
[out]	outBuf	A buffer descriptor containing an output buffer.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) speech decoder handle and the speech decoder is in the created state.

Return values:

	SPHDEC1_EOK	Success.
	SPHDEC1_EFAIL	Failure.
	SPHDEC1_EUNSUPPORTED	Unsupported request.

Remarks:

Since the SPHDEC1 decoder contains support for asynchronous buffer submission and retrieval, this API becomes known as synchronous in nature.

This is a blocking call, and will return after the data has been decoded.

The buffers supplied to SPHDEC1_process() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

See also:

SPHDEC1_create()

SPHDEC1_delete()

SPHDEC1_control()

SPHDEC1_processAsync()

SPHDEC1_processWait()

ISPHDEC1_Fxns()process()

XDAS_Int32 SPHDEC1_processAsync	(	SPHDEC1_Handle	handle,
		XDM1_SingleBufDesc *	inBuf,
		XDM1_SingleBufDesc *	outBuf,
		SPHDEC1_InArgs *	inArgs,
		SPHDEC1_OutArgs *	outArgs
	)

Perform asynchronous submission to this instance of a speech decoder algorithm.

Parameters:

[in]	handle	Handle to a created speech decoder instance.
[in]	inBuf	A buffer descriptor containing the input buffer.
[out]	outBuf	A buffer descriptor containing the output buffer.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) speech decoder handle and the speech decoder is in the created state.

Return values:

	SPHDEC1_EOK	Success.
	SPHDEC1_EFAIL	Failure.
	SPHDEC1_EUNSUPPORTED	Unsupported request.

Remarks:

This API is the asynchronous counterpart to the process() method. It allows for buffer and argument submission without waiting for retrieval. A response is retrieved using the SPHDEC1_processWait() API.

The buffers supplied to SPHDEC1_processAsync() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

See also:

SPHDEC1_create()

SPHDEC1_delete()

SPHDEC1_control()

SPHDEC1_process()

SPHDEC1_processWait()

ISPHDEC1_Fxns::process()

XDAS_Int32 SPHDEC1_processWait	(	SPHDEC1_Handle	handle,
		XDM1_SingleBufDesc *	inBuf,
		XDM1_SingleBufDesc *	outBuf,
		SPHDEC1_InArgs *	inArgs,
		SPHDEC1_OutArgs *	outArgs,
		UInt	timeout
	)

Wait for a return message from a previous invocation of SPHDEC1_processAsync() in this instance of an speech decoder algorithm.

Parameters:

[in]	handle	Handle to a created speech decoder instance.
[in]	inBuf	A buffer descriptor containing the input buffer.
[out]	outBuf	A buffer descriptor containing the output buffer.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.
[in]	timeout	Amount of "time" to wait (from 0 -> SPHDEC1_FOREVER)

Precondition:

handle is a valid (non-NULL) speech decoder handle and the speech decoder is in the created state.

Return values:

	SPHDEC1_EOK	Success.
	SPHDEC1_EFAIL	Failure.
	SPHDEC1_EUNSUPPORTED	Unsupported request.
	SPHDEC1_ETIMEOUT	Operation timed out.

Remarks:

This is a blocking call, and will return after the data has been decoded.

"Polling" is supported by using a timeout of 0. Waiting forever is supported by using a timeout of SPHDEC1_EFOREVER.

There must have previously been an invocation of the SPHDEC1_processAsync() API.

The buffers supplied to SPHDEC1_processAsync() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

See also:

SPHDEC1_create()

SPHDEC1_delete()

SPHDEC1_control()

SPHDEC1_process()

SPHDEC1_processAsync()