RSX 3D Contents Interfaces Data Structures Previous Next
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.
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;
This structure and the data pointed to by lpData, cannot be freed until RSX 3D signals the event designated by hEventSignal.
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;
- 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.
Specifies the synchronization group identifier for this emitter. Zero indicates this emitter is not part of a synchronization group.
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.
C:\media\hello.wav myapp.exe ID_SOUND1 mydll.dll 108 c:\mydir\hello.exe 200 http://www.mycompany.com/waves/test.wav
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 provides descriptive information about a direct audio listener.
typedef struct { DWORD cbSize; LPWAVEFORMATEX lpwf; HWND hMainWnd; DWORD dwUser; } RSXDIRECTLISTENERDESC;
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 defines the audio model properties for a sound emitter.
typedef struct { DWORD cbSize; float fMinBack; float fMinFront; float fMaxBack; float fMaxFront; float fIntensity; } RSXEMITTERMODEL;
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 defines the acoustic attributes for the audio environment.
typedef struct { DWORD cbSize; DWORD dwFlags; BOOL bUseRightHand; FLOAT fSpeedOfSound; enum RSX_CPU_Budget CPUBudget; } RSXENVIRONMENT;
RSXQUERYMEDIAINFO defines the current state of an emitter.
typedef struct { DWORD cbSize; DWORD dwControl; FLOAT fSecondsPlayed; FLOAT fTotalSeconds; DWORD dwNumLoops; FLOAT fAudibleLevel; } RSXQUERYMEDIAINFO;
RSXREVERBMODEL defines the reverberation model for the audio environment.
typedef struct { DWORD cbSize; BOOL bUseReverb; FLOAT fDecayTime; FLOAT fIntensity } RSXENVIRONMENT;
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 defines the relevant audio model properties for a streaming sound emitter.
typedef struct { DWORD cbSize; DWORD dwFlags; DWORD dwType; LPWAVEFORMATEX lpwf; DWORD dwUser; } RSXSTREAMINGEMITTERDESC;
RSXSTREAMINGLISTENERDESC provides descriptive information about a streaming listener.
typedef struct { DWORD cbSize; LPWAVEFORMATEX lpwf; DWORD dwRequestedBufferSize; DWORD dwActualBufferSize; DWORD dwUser; } RSXLISTENERDESC;
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