RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Data Structures

Many of the IRSX interface methods use data structures to pass and retrieve parameters. The following describes each of the data structures used by the Intel RSX 3D library.

NOTE. RSX 3D structures have a cbSize member that you must initialize when using these data structures. Functions return an E_INVALIDARG error code when called with an incorrect cbSize.

Data Structures and Descriptions

RSXBUFFERHDR
The structure for passing audio buffers with the streaming emitter and streaming listener.
 
RSXCACHEDEMITTERDESC
The description of the cached emitter used at the time of its creation.
 
RSXDIRECTLISTENERDESC
The audio model properties for a direct listener.
 
RSXEMITTERMODEL
The audio model properties for an emitter.
 
RSXENVIRONMENT
The acoustic attributes for the audio environment.
 
RSXQUERYMEDIAINFO
The state information for an emitter.
 
RSXREVERBMODEL
The acoustic model for reverberation.
 
RSXSTREAMINGEMITTERDESC
The description of the streaming emitter used at the time of its creation.
 
RSXSTREAMINGLISTENERDESC
The audio model properties for a streaming listener.
 
RSXVECTOR3D
A point in 3D space.

RSXBUFFERHDR

RSXBUFFERHDR defines the structure for passing audio buffers to the streaming emitter and streaming listener.

typedef struct {
	DWORD			cbSize;
	DWORD			dwUser;
	DWORD			dwSize;
	LPSTR			lpData;
	HANDLE			hEventSignal;
	DWORD			dwReserved1;
	DWORD			dwReserved2;
	DWORD			dwReserved3;
	DWORD			dwReserved4;
	DWORD			dwReserved5;
} RSXBUFFERHDR;
cbSize
Specifies the size, in bytes, of this data structure.
 
dwUser
Specifies a 32-bit word that you can use for storing pointers to other data structures useful in your application.
 
dwSize
Specifies the size, in bytes, of the buffer pointed to by the lpData field.
 
lpData
Points to the buffer allocated by the application containing the data to be played by the streaming emitter, or filled by the streaming listener.
 
hEventSignal
Win32 event handle to be signaled when RSX 3D finishes with the buffer. This is only used for the streaming emitter and must be NULL for the streaming listener.
 
dwReserved1 . . . dwReserved5
Reserved for use by RSX.
 

Comments

This structure and the data pointed to by lpData, cannot be freed until RSX 3D signals the event designated by hEventSignal.


RSXCACHEDEMITTERDESC

RSXCACHEDEMITTERDESC defines the relevant audio model properties for a cached sound-emitter.

typedef struct {
	DWORD		        cbSize;
	DWORD			dwFlags;
	DWORD			dwGroupID;
	char			szFilename[RSX_MAX_NAME_LEN];
	HANDLE			hEventSignal;
	DWORD			dwUser;
} RSXCACHEDEMITTERDESC;
cbSize
Specifies the size, in bytes, of this data structure.
 
dwFlags
Specifies flags used for creating the cached emitter. The following flags can be combined by using the bitwise OR operator:
RSXEMITTERDESC_GROUPID
Indicates this emitter is part of the group identified by the dwGroupID member.
RSXEMITTERDESC_NODOPPLER
Indicates Doppler effects should not be calculated for this emitter.

RSXEMITTERDESC_NOATTENUATE

Indicates distance attenuation should not be performed on this emitter. This
flag is only valid if the RSXEMITTERDESC_NOSPATIALIZE flag is also specified.

RSXEMITTERDESC_NOSPATIALIZE

Indicates spatialization should not be performed on this emitter.
Distance attenuation will still be provided unless the RSXEMITTERDESC_NOATTENUATE flag is also specified.

RSXEMITTERDESC_NOREVERB

Indicates this emitter should not be included in reverberation.

RSXEMITTERDESC_PREPROCESS

Indicates the emitter should be preprocessed for greatest run-time efficiency. This potentially increases the creation time for the emitter, requiring the entire contents of the specified file to be manipulated. A temporary file is written to disk that contains the preprocessed file. The file is deleted when the emitter is released. Preprocessing only applies to non-PCM wave files. The ACM conversion will be done at file load time instead of during playback time. Thus the time to create the emitter may be slightly longer but audio playback will consume less CPU.

RSXEMITTERDESC_INMEMORY

Indicates the emitter is completely loaded in memory. This potentially increases the creation time for the emitter, requiring the entire contents of the specified file to loaded into main memory.

dwGroupID

Specifies the synchronization group identifier for this emitter. Zero indicates this emitter is not part of a synchronization group.

szFileName

The full path to the sound file or the name of a module and the numeric identifier for a resource in the module that contains the audio data for this sound emitter.

Note that the module (.exe or .dll) containing the resource must be in the same Win32 process space as rsx.dll. Resources must be identified with a numeric identifier and not a string. The module name must be one and only one word (for example, 'app.exe' but not 'my really cool app.exe').

If you have Microsoft Internet Explorer 3.0 (or later) installed and configured correctly you may also supply a URL for this parameter.

 
Examples:
C:\media\hello.wav
myapp.exe ID_SOUND1
mydll.dll 108
c:\mydir\hello.exe 200 
http://www.mycompany.com/waves/test.wav
 
hEventSignal
Win32 event handle to be signaled when RSX 3D finishes playing the emitter. If this member is NULL, no notification will be provided.
 
dwUser
32 bits of instance data assigned by the application.

Comments

The RSXEMITTERDESC_PREPROCESS and RSXEMITTERDESC_INMEMORY flags can be combined to force the cached emitter to respond like the emitter's defined in RSX 1.0. In RSX 1.0, all emitter data was preprocessed and stored in main memory.


RSXDIRECTLISTENERDESC

RSXDIRECTLISTENERDESC provides descriptive information about a direct audio listener.

typedef struct {
	DWORD				cbSize;
	LPWAVEFORMATEX		        lpwf;
	HWND				hMainWnd;
	DWORD				dwUser;
} RSXDIRECTLISTENERDESC;

 

cbSize
Specifies the size, in bytes, of this data structure.
 
lpwf
Specifies a pointer to a WAVEFORMATEX structure that specifies the format RSX should attempt to use when using the audio device. For the default audio format, this member should be NULL.
 
hMainWnd
The window handle of the application's main window.
 
dwUser
32 bits of instance data assigned by the application.

Comments

RSX 3D can be configured by an end user to use DirectSound, which requires the main window handle of the application. If DirectSound rejects the window handle specified in the hMainWnd member, the RSX 3D library will use the higher latency Wave API.


RSXEMITTERMODEL

RSXEMITTERMODEL defines the audio model properties for a sound emitter.

typedef struct {
	DWORD			cbSize;
	float			fMinBack;
	float			fMinFront;
	float			fMaxBack;
	float			fMaxFront;
	float			fIntensity;
} RSXEMITTERMODEL;

 

cbSize
Specifies the size, in bytes, of this data structure.
 
fMinBack
Specifies the minimum back range.
 
fMinFront
Specifies the minimum front range.
 
fMaxBack
Specifies the maximum back range.
 
fMaxFront
Specifies the maximum front range.
 
fIntensity
Specifies the emitter's static intensity. This value should be in the range of 0 to 1.0. Values outside this range may cause clipping which degrades audio quality.

Comments

RSX 3D models an emitter in terms of two concentric elliptical regions. These two ellipses describe an ambient region and an attenuation region. You can adjust the shape of these ellipses to vary the directionality of the emitter.

Inside the ellipsoid that is defined by fMinBack and fMinFront, the sound is a constant (maximum) intensity and contains no directional information. This region models what we would normally consider "ambient sounds. "

The outer ellipse, identified by fMaxFront and fMaxBack, defines the attenuation region. Within this region, audio is localized, and the intensity decreases logarithmically. Beyond the outer ellipse, the intensity is zero.

For both of these regions, the front values must be greater than the associated back values. If the fMaxBack or fMinBack values are zero, RSX 3D calculates the natural (inverse square) attenuation and modifies these parameters.


RSXENVIRONMENT

RSXENVIRONMENT defines the acoustic attributes for the audio environment.

typedef struct {
	DWORD			cbSize;
	DWORD			dwFlags;
	BOOL			bUseRightHand;
	FLOAT			fSpeedOfSound;
	enum RSX_CPU_Budget	CPUBudget;
} RSXENVIRONMENT;

 

cbSize
Specifies the size, in bytes, of this data structure.
 
dwFlags
Specifies flags used for creating the RSX 3D environment. The following flags can be combined by using the bitwise OR operator:
 
RSXENVIRONMENT_COORDINATESYSTEM
Indicates a change in coordinate system mappings, as specified by the bUseRightHand member.
 
RSXENVIRONMENT_SPEEDOFSOUND
Indicates the speed of sound, as specified by the fSpeedOfSound member.
 
bUseRightHand
If TRUE, sets the coordinate system to use right-handed notation instead of the default left-handed coordinate mapping.
 
fSpeedOfSound
The speed (in generic units/sec) at which sound travels through the medium. This value is used for applying Doppler effects when a sound emitter has a non-zero velocity relative to the listener. A value of zero indicates Doppler effects should not be applied.
 
CPUBudget
This field is not used.

RSXQUERYMEDIAINFO

RSXQUERYMEDIAINFO defines the current state of an emitter.

typedef struct {
	DWORD			cbSize;
	DWORD			dwControl;
	FLOAT			fSecondsPlayed;
	FLOAT			fTotalSeconds;
	DWORD			dwNumLoops;
	FLOAT			fAudibleLevel;
	
} RSXQUERYMEDIAINFO;
cbSize
Specifies the size, in bytes, of this data structure.
 
dwControl
Specifies the play state of the emitter. For streaming emitters, this value is always RSX_PLAY.
 
fSecondsPlayed
Specifies the emitter's playback position in seconds. For streaming emitters, this indicates the cumulative play position.
 
fTotalSeconds
Specifies the emitter's total play time in seconds. For streaming emitters, this value is not used and will be returned as zero.
 
dwNumLoops
Specifies the loop count for the emitter. For streaming emitters, this value is not used and will be returned as zero.
 
fAudibleLevel
Specifies the audible level for the emitter. RSX 3D calculates the audible level based on the distance between the emitter and the listener; the play state has no effect on the audio level. A value of zero indicates the emitter is not audible. This value will never be greater than the intensity set for the emitter. An application can use this information to implement various priority schemes to moderate which sounds should be rendered.

RSXREVERBMODEL

RSXREVERBMODEL defines the reverberation model for the audio environment.

typedef struct {
	DWORD			cbSize;
	BOOL			bUseReverb;
	FLOAT			fDecayTime;
	FLOAT			fIntensity
} RSXENVIRONMENT;

 

cbSize
Specifies the size, in bytes, of this data structure.
 
bUseReverb
If TRUE, activates the use of reverberation with the characteristics specified by the fDecayTime and fIntensity members.
 
fDecayTime
Specifies the reverberation decay time in seconds. This value must be in the range of 0 to 3 seconds. Refer to the table below for suggested values.
 
fIntensity
Specifies the reverberation gain used to model sound absorption. This value should be in the range of 0 to 1. Refer to Table1 for suggested values.

Comments

Table 1 shows some common reverberation parameters you can use to define a reverberation model for your application's audio environment.

Table 1. Common Reverberation Parameters

Room Type Decay Time Intensity
ROOM 0.5 0.2
CHAMBER 1.0 0.2
STAGE 1.5 0.2
HALL 2.0 0.2
PLATE 2.5 0.2

RSXSTREAMINGEMITTERDESC

RSXSTREAMINGEMITTERDESC defines the relevant audio model properties for a streaming sound emitter.

typedef struct {
	DWORD			cbSize;
	DWORD			dwFlags;
	DWORD			dwType;
	LPWAVEFORMATEX		lpwf;
	DWORD			dwUser;
} RSXSTREAMINGEMITTERDESC;

 

cbSize
Specifies the size, in bytes, of this data structure.
 
dwFlags
Specifies flags used for creating the streaming emitter. The following flags can be combined by using the bitwise OR operator:
 
RSXEMITTERDESC_NOATTENUATE
Indicates distance attenuation should not be performed on this emitter. This flag is only valid if the RSXEMITTERDESC_NOSPATIALIZE flag is also specified.
 
RSXEMITTERDESC_NODOPPLER
Indicates Doppler effects should not be calculated for this emitter.
 
RSXEMITTERDESC_NOSPATIALIZE
Indicates spatialization should not be performed on this emitter. Distance attenuation will still be provided unless the RSXEMITTERDESC_NOATTENUATE flags is also specified.
 
RSXEMITTERDESC_NOREVERB
Indicates this emitter should not be included in reverberation.
 
dwType
Identifies the type of streaming data. This parameter is currently not used and must be zero.
 
lpwf
Specifies the format of the stream to be used for this emitter. This format may be anything resolvable to PCM by installed ACM drivers.
 
dwUser
32 bits of instance data assigned by the application.

RSXSTREAMINGLISTENERDESC

RSXSTREAMINGLISTENERDESC provides descriptive information about a streaming listener.

typedef struct {
	DWORD			cbSize;
	LPWAVEFORMATEX		lpwf;
	DWORD			dwRequestedBufferSize;
	DWORD			dwActualBufferSize;
	DWORD			dwUser;
} RSXLISTENERDESC;
cbSize
Specifies the size, in bytes, of this data structure.
 
lpwf
Pointer to a WAVEFORMATEX structure that specifies the format of the buffers to be provided by the streaming listener when IRSXStreamingListener::RequestBuffer is called. If a type other than PCM is specified, a conversion will be required.
 
dwRequestedBufferSize
Specifies the size, in bytes, of the buffers the application would like to use with the streaming listener interface.
 
dwActualBufferSize
Specifies the actual size, in bytes, of the buffers RSX 3D can return to the application through the streaming listener interface. This value is set by RSX 3D.

RSXVECTOR3D

RSXVECTOR3D stores the x, y, and z information for a 3D vector.

typedef struct {
	float			x;
	float			y;
	float			z;
} RSXVECTOR3D;

RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Copyright ©1996, 1997 Intel Corporation. All rights reserved