CriAtomAwb API

宏定义
#define	CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY   (64)
	Work area size required for creating on-memory AWB handle 更多...
#define	CRIATOMAWB_ILLEGAL_ID   (-1)
	Invalid waveform data ID 更多...
#define	CRIATOM_DEFAULT_DBAS_MAX_BPS
	Default initialization maximum bit rate for creating D-BAS 更多...

类型定义
typedef struct CriAtomAwbTag *	CriAtomAwbHn
	AWB handle 更多...
typedef enum CriAtomAwbStatusTag	CriAtomAwbStatus
	AWB status 更多...
typedef enum CriAtomAwbTypeTag	CriAtomAwbType
	AWB type 更多...

枚举
enum	CriAtomAwbStatusTag { CRIATOMAWB_STATUS_STOP = 0 , CRIATOMAWB_STATUS_LOADING , CRIATOMAWB_STATUS_COMPLETE , CRIATOMAWB_STATUS_ERROR , CRIATOMAWB_STATUS_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	AWB status 更多...
enum	CriAtomAwbTypeTag { CRIATOMAWB_TYPE_TOC = 0 , CRIATOMAWB_TYPE_ONMEMORY , CRIATOMAWB_TYPE_ERROR , CRIATOMAWB_TYPE_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	AWB type 更多...

函数
CriSint32	criAtomAwb_CalculateWorkSizeForLoadToc (CriSint32 num)
	Calculate work area size required for loading AWB file's TOC information 更多...
CriAtomAwbHn	criAtomAwb_LoadToc (CriFsBinderHn binder, const CriChar8 *path, void *work, CriSint32 work_size)
	Load AWB file's TOC information (synchronous version) 更多...
CriAtomAwbHn	criAtomAwb_LoadTocById (CriFsBinderHn binder, CriUint16 id, void *work, CriSint32 work_size)
	Load AWB file's TOC information specifying ID (synchronous version) 更多...
CriAtomAwbHn	criAtomAwb_LoadTocAsync (CriFsBinderHn binder, const CriChar8 *path, void *work, CriSint32 work_size)
	Load AWB file's TOC information (asynchronous version) 更多...
CriAtomAwbHn	criAtomAwb_LoadTocAsyncById (CriFsBinderHn binder, CriUint16 id, void *work, CriSint32 work_size)
	Load AWB file's TOC information specifying ID (asynchronous version) 更多...
CriAtomAwbHn	criAtomAwb_LoadFromMemory (void *awb_mem, CriSint32 awb_mem_size, void *work, CriSint32 work_size)
	Create on-memory AWB handle 更多...
CriAtomAwbType	criAtomAwb_GetType (CriAtomAwbHn awb)
	Get value indicating AWB handle type 更多...
CriBool	criAtomAwb_GetWaveFileInfo (CriAtomAwbHn awb, CriSint32 id, CriSint64 *offset, CriUint32 *size)
	Get wave data file information from AWB TOC information 更多...
void	criAtomAwb_GetWaveDataInfo (CriAtomAwbHn awb, CriSint32 id, void **wave_data_start, CriUint32 *size)
	Get wave data information from on-memory AWB 更多...
CriUint16	criAtomAwb_GetNumContents (CriAtomAwbHn awb)
	Get number of contents in AWB file through AWB handle 更多...
void	criAtomAwb_Release (CriAtomAwbHn awb)
	Release AWB handle 更多...
CriBool	criAtomAwb_IsReadyToRelease (CriAtomAwbHn awb)
	Check whether AWB handle can be released immediately 更多...
CriAtomAwbStatus	criAtomAwb_GetStatus (CriAtomAwbHn awb)
	Get AWB handle status 更多...
CriSint32	criAtomAwb_GetIdByIndex (CriAtomAwbHn awb, CriUint16 index)
	Get waveform data ID 更多...
CriFloat32	criAtomDsp_ConvertParameterFromCent (CriFloat32 cent)
	Convert from cent to DSP parameter 更多...

详细描述

宏定义说明

CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY

#define CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY   (64)

Work area size required for creating on-memory AWB handle

Description:

Work area size required for creating on-memory AWB handle.

参见

criAtomAwb_LoadFromMemory

CRIATOMAWB_ILLEGAL_ID

#define CRIATOMAWB_ILLEGAL_ID   (-1)

Invalid waveform data ID

Description:

The value returned when the criAtomAwb_GetIdByIndex function fails.

参见

criAtomAwb_GetIdByIndex

CRIATOM_DEFAULT_DBAS_MAX_BPS

#define CRIATOM_DEFAULT_DBAS_MAX_BPS

值:

    (criAtom_CalculateAdxBitrate(CRIATOM_DEFAULT_INPUT_MAX_CHANNELS,\
                                 CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE)\
                                 * CRIATOM_DEFAULT_DBAS_MAX_STREAMS)

Default initialization maximum bit rate for creating D-BAS

Description:

Default initialization maximum bit rate for creating D-BAS.
This value is calculated for the default maximum number of streams defined on each platform, assuming streaming playback of stereo ADX data.

参见

criAtomDbas_Create, criAtomDbas_CalculateWorkSize, criAtom_CalculateAdxBitrate

类型定义说明

CriAtomAwbHn

typedef struct CriAtomAwbTag* CriAtomAwbHn

AWB handle

Description:

Handle indicating the TOC information of the AWB file containing the playback data.
It is obtained with the criAtomAwb_LoadToc function.

参见

criAtomAwb_LoadToc

CriAtomAwbStatus

typedef enum CriAtomAwbStatusTag CriAtomAwbStatus

AWB status

Description:

Indicates the preparation status of an AWB.
It is obtained with the criAtomAwb_GetStatus function.

参见

criAtomAwb_GetStatus

CriAtomAwbType

typedef enum CriAtomAwbTypeTag CriAtomAwbType

AWB type

Description:

Indicates whether the AWB handle contains only the TOC information, or is an actual AWB handle loaded onto the memory. It is obtained with the criAtomAwb_GetType function.

参见

criAtomAwb_GetType

枚举类型说明

CriAtomAwbStatusTag

enum CriAtomAwbStatusTag

AWB status

Description:

Indicates the preparation status of an AWB.
It is obtained with the criAtomAwb_GetStatus function.

参见

criAtomAwb_GetStatus

枚举值
CRIATOMAWB_STATUS_STOP	Stopped
CRIATOMAWB_STATUS_LOADING	Loading
CRIATOMAWB_STATUS_COMPLETE	Load complete
CRIATOMAWB_STATUS_ERROR	Load failed

CriAtomAwbTypeTag

enum CriAtomAwbTypeTag

AWB type

Description:

Indicates whether the AWB handle contains only the TOC information, or is an actual AWB handle loaded onto the memory. It is obtained with the criAtomAwb_GetType function.

参见

criAtomAwb_GetType

枚举值
CRIATOMAWB_TYPE_TOC	AWB handle with TOC information only
CRIATOMAWB_TYPE_ONMEMORY	On-memory AWB handle
CRIATOMAWB_TYPE_ERROR	Invalid AWB handle

函数说明

criAtomAwb_CalculateWorkSizeForLoadToc()

CriSint32 criAtomAwb_CalculateWorkSizeForLoadToc

(

CriSint32

num

)

Calculate work area size required for loading AWB file's TOC information

参数

[in]

num

number of contents in AWB file

返回

CriSint32 work area size

返回值

>=	0 successfully completed
-1	error occurred

Description:

Retrieves the work area size required for loading the AWB file TOC information.

If work area size calculation fails, this function returns -1.
The reason for work area size calculation failure can be determined by viewing the error callback message.

注意

You must initialize the library before executing this function.

参见

criAtomAwb_LoadToc, criAtomAwb_LoadTocAsync

criAtomAwb_LoadToc()

CriAtomAwbHn criAtomAwb_LoadToc	(	CriFsBinderHn	binder,
		const CriChar8 *	path,
		void *	work,
		CriSint32	work_size
	)

Load AWB file's TOC information (synchronous version)

参数

[in]	binder	binder handle
[in]	path	AWB file name
[in]	work	AWB file TOC information load work area
[in]	work_size	work area size

返回

CriAtomAwbHn AWB handle

Description:

Loads the TOC information for an AWB file used as the sound source for sound playback.
Execute when scene switching or variation in load is permissible because this function does not return until loading completes.
When loading succeeds, a valid AWB handle is returned which should be specified in the criAtomPlayer_SetWaveId function.
Release the finished AWB handle with the criAtomAwb_Release function.
NULL is returned if loading of TOC information fails.

Remarks:

If this function is executed specifying NULL as the third argument and 0 as the fourth argument, the required work area is dynamically allocated within the function. The dynamically allocated area is released with the criAtomAwb_Release function.

注意

An AWB handle internally allocates a binder ( CriFsBinderHn ) and loader ( CriFsLoaderHn ).
When loading AWB file TOC information, Atom library (or CRI File System library) must be initialized with setting that can allocate as many binders and loaders as the number of AWB handles.

参见

criAtomPlayer_SetWaveId, criAtomAwb_Release, criAtomAwb_LoadTocById

criAtomAwb_LoadTocById()

CriAtomAwbHn criAtomAwb_LoadTocById	(	CriFsBinderHn	binder,
		CriUint16	id,
		void *	work,
		CriSint32	work_size
	)

Load AWB file's TOC information specifying ID (synchronous version)

参数

[in]	binder	binder handle
[in]	id	ID of CPK content containing AWB file
[in]	work	AWB file TOC information load work area
[in]	work_size	work area size

返回

CriAtomAwbHn AWB handle

Description:

This function is similar to the criAtomAwb_LoadToc function. However, unlike the criAtomAwb_LoadToc function, this function specifies content ID in the CPK rather than the path to load AWB file TOC information.

参见

criAtomPlayer_SetWaveId, criAtomAwb_Release, criAtomAwb_LoadToc

criAtomAwb_LoadTocAsync()

CriAtomAwbHn criAtomAwb_LoadTocAsync	(	CriFsBinderHn	binder,
		const CriChar8 *	path,
		void *	work,
		CriSint32	work_size
	)

Load AWB file's TOC information (asynchronous version)

参数

[in]	binder	binder handle
[in]	path	AWB file name
[in]	work	AWB file TOC information load work area
[in]	work_size	work area size

返回

CriAtomAwbHn AWB handle

Description:

Loads the TOC information for an AWB file used as the sound source for sound playback.
Because this is an asyncrhonous function that issues load request, an application must wait until load completes.
Periodically retrieve the status of AWB handle with the criAtomAwb_GetStatus function and wait unitl load completes.
While waiting for load to complete, the criAtom_ExecuteMain function must be executed periodically to update the status of the AWB handle.
When issuing of load request succeeds, a valid AWB handle is returned.
After load completes successfully, specify this in the criAtomPlayer_SetWaveId function.
Release the finished AWB handle with the criAtomAwb_Release function.
NULL is returned if issuing of TOC information load request fails.

Remarks:

If this function is executed specifying NULL as the third argument and 0 as the fourth argument, the required work area is dynamically allocated within the function. The dynamically allocated area is released with the criAtomAwb_Release function.
When the status of AWB handle obtained with this function is error (CRIATOMAWB_STATUS_ERROR), also release with the criAtomAwb_Release function.

注意

An AWB handle internally allocates a binder ( CriFsBinderHn ) as the number of Voices.
When loading AWB file TOC information, Atom library (or CRI File System library) must be initialized with setting that can allocate as many binders and this function.

参见

criAtomPlayer_SetWaveId, criAtomAwb_Release, criAtomAwb_GetStatus, criAtomAwb_LoadTocAsyncById

criAtomAwb_LoadTocAsyncById()

CriAtomAwbHn criAtomAwb_LoadTocAsyncById	(	CriFsBinderHn	binder,
		CriUint16	id,
		void *	work,
		CriSint32	work_size
	)

Load AWB file's TOC information specifying ID (asynchronous version)

参数

[in]	binder	binder handle
[in]	id	ID of CPK content containing AWB file
[in]	work	AWB file TOC information load work area
[in]	work_size	work area size

返回

CriAtomAwbHn AWB handle

Description:

This function is similar to the criAtomAwb_LoadTocAsync function. However, unlike the criAtomAwb_LoadTocAsync function, this function specifies content ID in the CPK rather than the path to load AWB file TOC information.

参见

criAtomPlayer_SetWaveId, criAtomAwb_Release, criAtomAwb_GetStatus, criAtomAwb_LoadTocAsync

criAtomAwb_LoadFromMemory()

CriAtomAwbHn criAtomAwb_LoadFromMemory	(	void *	awb_mem,
		CriSint32	awb_mem_size,
		void *	work,
		CriSint32	work_size
	)

Create on-memory AWB handle

参数

[in]	awb_mem	pointer to memory area in which AWB file is loaded
[in]	awb_mem_size	AWB file size
[in]	work	pointer to on-memory AWB work area
[in]	work_size	on-memory AWB work area size

返回

CriAtomAwbHn on-memory AWB handle

Description:

Creates an on-memory AWB handle from an AWB file image loaded in memory.
Multiple on-memory AWB handles can be created from the same on-memory AWB file image.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.

When using the User Allocator method, you do not need to provide a work area.
You can allocate the required memory with the registered memory allocation function simply by specifying NULL for work and 0 for work_size.
The memory dynamically allocated when creating on-memory AWB handle is
released when on-memory AWB is destroyed (when criAtomAwb_Release function is executed).
When using Fixed Memory method, obtain the required work area size with the CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY function.
Please note that unlike work areas, awb_mem must be managed by the user.

注意

When this function succeeds, the memory area passed with awb_mem is overwritten for on-memory AWB data.
Therefore, if the CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY function is called from multiple threads,
the thread execution sequence may be changed due to exclusive control.
Please manually release the memory area pointed to by awb_mem after executing the criAtomAwb_Release function.
An AWB handle internally allocates a binder ( CriFsBinderHn ).
When AWB file TOC information is loaded, the Atom library (or CRI File System library) must be initialized with the setting that can allocate as many binders as the number of AWB handles.

参见

CRIATOMAWB_WORKSIZE_FOR_LOADFROMMEMORY,criAtomAwb_Release

criAtomAwb_GetType()

CriAtomAwbType criAtomAwb_GetType

(

CriAtomAwbHn

awb

)

Get value indicating AWB handle type

参数

[in]

awb

information source AWB handle

返回

CriAtomAwbType value indicating AWB handle type

Description:

Obtains a value indicating whether the AWB handle contains only the TOC information, or is an actual AWB handle loaded onto the memory. If this function fails, CRIATOMAWB_TYPE_ERROR is returned.

参见

criAtomAwb_GetWaveDataInfo, criAtomPlayer_SetData,

criAtomAwb_GetWaveFileInfo()

CriBool criAtomAwb_GetWaveFileInfo	(	CriAtomAwbHn	awb,
		CriSint32	id,
		CriSint64 *	offset,
		CriUint32 *	size
	)

Get wave data file information from AWB TOC information

参数

[in]	awb	information source AWB handle
[in]	id	wave data ID
[out]	offset	wave data offset (bytes)
[out]	size	wave data size (bytes)

返回

None

Description:

For an AWB handle, obtains the file offset and size of wave data specified with id.
The obtained offset and size are used when directly reading wave data from AWB file.

注意

Check the type of AWB handle with the criAtomAwb_GetType function before executing this function.
If the AWB handle type is different or the AWB handle is invalid, this function fails and an error callback occurs.
If this function fails, the output offset and size are undefined.

参见

criAtomAwb_GetType, criAtomAwb_GetWaveDataInfo, criAtomPlayer_SetData,criAtomAwb_GetType

criAtomAwb_GetWaveDataInfo()

void criAtomAwb_GetWaveDataInfo	(	CriAtomAwbHn	awb,
		CriSint32	id,
		void **	wave_data_start,
		CriUint32 *	size
	)

Get wave data information from on-memory AWB

参数

[in]	awb	information source AWB handle
[in]	id	wave data ID
[out]	wave_data_start	wave data pointer (bytes)
[out]	size	wave data size (bytes)

返回

None

Description:

For an on-memory AWB, obtains the pointer and size of wave data specified with id.
When playing wave data from on-memory AWB, also refer to the criAtomPlayer_SetWaveId function because this is normally sufficient.

注意

Check the type of AWB handle with the criAtomAwb_GetType function before executing this function.
If the AWB handle type is different or the AWB handle is invalid, this function fails and an error callback occurs.
If this function fails, the output wave_data_start and size are undefined.

参见

criAtomAwb_GetType, criAtomAwb_GetWaveFileInfo, criAtomPlayer_SetData,criAtomPlayer_SetWaveId

criAtomAwb_GetNumContents()

CriUint16 criAtomAwb_GetNumContents

(

CriAtomAwbHn

awb

)

Get number of contents in AWB file through AWB handle

参数

[in]

awb

information source AWB handle

返回

number of content files (0 to 65535)

Description:

Gets the number of contents (wave data) in an AWB file through an AWB handle.
The valid range for the number of content files is from 1 to 65535.
Zero is returned when there is an error.

参见

criAtomAwb_LoadToc, criAtomAwb_LoadFromMemory

criAtomAwb_Release()

void criAtomAwb_Release

(

CriAtomAwbHn

awb

)

Release AWB handle

参数

[in]

awb

AWB handle

返回

None

Description:

Releases an AWB handle.
Release the finished AWB handle with this function.
Do not use the released AWB handle because it will become an invalid handle.

注意

When this function is executed, the Atom player referencing the specified AWB data does not exist or the library is searched.
Therefore, if an Atom Player is created/destroyed on another thread while this function is in process, a serious problem such as an access violation or deadlock may be induced.
If you need to create/destroy an Atom Player on another thread while this function is in process, Lock this function with the criAtom_Lock function before executing.

When playing an AWB file using an AtomEx player, do not destroy the AWB handle by this function during playback.
Please make sure to execute this function after stopping the AtomEx player.

参见

criAtomAwb_LoadToc, criAtomAwb_LoadTocAsync, criAtomAwb_GetStatus

criAtomAwb_IsReadyToRelease()

CriBool criAtomAwb_IsReadyToRelease

(

CriAtomAwbHn

awb

)

Check whether AWB handle can be released immediately

参数

[in]

awb

AWB handle

返回

CriBool AWB status (CRI_TRUE = immediate release allowed, CRI_FALSE = active player present)

Description:

Checks whether an AWB handle can be released immediately.
When the criAtomAwb_Release function is executed when this function returns CRI_FALSE, the player accessing the AWB handle is stopped.
(In the case of AWB handle for stream playback, processing may be blocked for a long time within the criAtomAwb_Release function while waiting for file load to complete.)

注意

When this function is executed, the Atom player referencing the specified AWB data does not exist or the library is searched.
Therefore, if an Atom Player is created/destroyed on another thread while this function is in process, a serious problem such as an access violation or deadlock may be induced.
If you need to create/destroy an Atom Player on another thread while this function is in process, Lock this function with the criAtom_Lock function before executing.

参见

criAtomAwb_Release

criAtomAwb_GetStatus()

CriAtomAwbStatus criAtomAwb_GetStatus

(

CriAtomAwbHn

awb

)

Get AWB handle status

参数

[in]

awb

AWB handle

返回

CriAtomAwbStatus value indicating the AWB handle status

Description:

Obtains the AWB handle status.
The status of the AWB handle obtained with this function is updated by executing the criAtom_ExecuteMain function.

参见

criAtomAwb_LoadToc, criAtomAwb_LoadTocAsync

criAtomAwb_GetIdByIndex()

CriSint32 criAtomAwb_GetIdByIndex	(	CriAtomAwbHn	awb,
		CriUint16	index
	)

Get waveform data ID

参数

[in]	awb	AWB Handle
[in]	index	Waveform Index

返回值

Waveform	data ID (0 or more) Processing completed successfully
CRIATOMAWB_ILLEGAL_ID	(-1) An error has occured

Description:

Gets the waveform data ID specified by index from the AWB handle.

参见

criAtomAwb_LoadToc, criAtomAwb_LoadTocAsync

criAtomDsp_ConvertParameterFromCent()

CriFloat32 criAtomDsp_ConvertParameterFromCent

(

CriFloat32

cent

)

Convert from cent to DSP parameter

参数

[in]

cent

Cent value

返回

CriFloat32 DSP parameter value

Description:

Normalizes a range of -1200 to 1200 to a range of 0.0f to 1.0f.