RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Interfaces

IRSXEmitter Abstract Base Class

The IRSXEmitter is an abstract base class defining the general characteristics of audio emitters. This interface controls the media behavior, position, and orientation of the emitters in the audio environment. The supported emitter types, IRSXCachedEmitter and IRSXStreamingEmitter, provide this functionality through their interfaces.

NOTE: An application cannot use the IRSXEmitter interface directly. It is encapsulated as part of a specific emitter, such as the IRSXCachedEmitter or the IRSXStreaming Emitter.

IRSXEmitter Abstract Base Class Methods and Meaning

GetCPUBudget
Retrieves the emitter's processing budget.
 
GetModel
Retrieves the emitter's sound model.
 
GetMuteState
Retrieves the emitter's mute state.
 
GetOrientation
Retrieves the orientation of the emitter in 3D space.
 
GetPitch
Retrieves the pitch adjustment of the emitter.
 
GetPosition
Retrieves the position of the emitter in 3D space.
 
GetUserData
Retrieves the emitter's user-specified data.
 
QueryMediaState
Queries the state of a sound emitter.
 
SetCPUBudget
Sets the processing budget for the emitter.
 
SetModel
Sets the sound model of a sound emitter.
 
SetMuteState
Sets the emitter's mute state.
 
SetOrientation
Orients the audio emitter in 3D space.
 
SetPitch
Sets the pitch adjustment of the emitter.
 
SetPosition
Positions the audio emitter in 3D space.

GetCPUBudget

Retrieves the emitter's processing budget.

Syntax

HRESULT GetCPUBudget(lpCPUBudget) 

Parameters

RSX_CPU_Budget * lpCPUBudget
Pointer to an RSX_CPU_Budget enumerated-type that will be filled with the emitter's processing budget for audio localization quality.

Returns

S_OK
E_INVALIDARG
E_NOTIMPL

Description

The processing budget value for a single emitter can be different from the application-wide processing budget specified by the SetEnvironment method. RSX uses this value as a guide when it determines to what extent it must localize a specific sound.

See Also

SetCPUBudget

NOTE. RSX 3D does not currently support GetCPUBudget and SetCPUBudget.


GetModel

Retrieves the emitter's model parameters.

HRESULT GetModel(lpEmitterModel)

Parameters

LPRSXEMITTERMODEL lpEmitterModel
Pointer to a RSXEMITTERMODEL that will be filled with the emitter's model parameters.

Returns

S_OK
E_INVALIDARG

Description

The emitter's model parameters describe the front and back ranges for the ambient and attenuation regions of the RSX 3D sound model. Adjusting these parameters varies the directionality of the emitter.

Usage Sample

// This is how you can retrieve the emitter's
// sound model.

RSXEMITTERMODEL rsxEModel;

m_lpCE->GetModel(&rsxEModel);

See Also

SetModel

GetMuteState

Retrieves the mute state of the emitter.

HRESULT GetMuteState (lpdwMuteState)

Parameters

LPDWORD lpdwMuteState
Pointer to a DWORD-sized location that will be filled with the emitter's mute state. Zero indicates the emitter is not muted and may be audible.

Returns

S_OK
E_INVALIDARG

Description

When mute is set, the returned value for lpdwMuteState is non-zero. When an emitter is mute, it still maintains its correct play position.

Usage Sample

// This is how you can retrieve the emitter's mute state

DWORD dwMuteState;
m_lpCE -> GetMuteState(&dwMuteState);
. . .

See Also

SetMuteState

GetOrientation

Retrieves a 3D vector that points in the same direction as the emitter's orientation.

HRESULT GetOrientation(lpOrientation)

Parameters

LPRSXVECTOR3D lpOrientation
Pointer to a RSXVECTOR3D that will be filled with the emitter's orientation.

Returns

S_OK
E_INVALIDARG

Description

An emitter's orientation is the direction of the sound from the emitter.

Usage Sample

// This is how you can retrieve the emitter's
// orientation.
      	
RSXVECTOR3D v3d;
m_lpCE->GetOrientation(&v3d);
. . .

See Also

SetOrientation

GetPitch

Retrieves the pitch adjustment of the emitter.

HRESULT GetPitch(lpfPitch)

Parameters

PFLOAT lpfPitch
Pointer to a FLOAT-sized location that will be filled with the emitter's pitch adjustment.

Returns

S_OK
E_INVALIDARG

Description

Pitch is the height or depth of an emitter's tone. A pitch factor of 1.0 is the default and causes no change in pitch. Valid pitch values range from 0.25 to 4.0. A pitch of 0.25 indicates a deep tone, whereas a pitch of 4.0 indicates a high, shrill tone. When an emitter's pitch changes, its timing also changes in proportion to the pitch.

Usage Sample

// This is how you can retrieve the emitter's
// pitch setting.

FLOAT fPitch;
m_lpCE->GetPitch(fPitch);
. . .

See Also

SetPitch

GetPosition

Retrieves the X,Y,Z coordinates of the emitter.

HRESULT GetPosition(lpPosition)

Parameters

LPRSXVECTOR3D lpPosition
Pointer to a RSXVECTOR3D that will be filled with the emitter's position.
 

Returns

S_OK
E_INVALIDARG
 

Description

Position describes the emitter's location in the 3D audio environment.

Usage Sample

// This is how you can retrieve the emitter's
// position.

RSXVECTOR3D v3d;      	
m_lpCE->GetPosition(&v3d);
. . .

See Also

SetPosition

GetUserData

Retrieves the user-defined data for the emitter.

HRESULT GetUserData(lpdwUser)
 

Parameters

LPDWORD lpdwUser
Pointer to a DWORD-size location to be filled with the user-defined data assigned to the specified emitter.

Returns

S_OK
E_INVALIDARG

Description

User data is a 32-bit word that you can use to store pointers to other data structures.

Usage Sample

// This is how you can retrieve the emitter's
// user data.
      	
DWORD dwUser;
m_lpCE->GetUserData(&dwUser);
. . .

QueryMediaState

Queries the state of the emitter.

HRESULT QueryMediaState(lpQueryMediaInfo)

Parameters

LPRSXQUERYMEDIAINFO lpQueryMediaInfo
Pointer to a RSXQUERYMEDIAINFO data structure to be filled with the emitter's current media state.

Returns

S_OK
E_INVALIDARG
 

Description

The state of the emitter is returned. See the IRSXCachedEmitter interface's ControlMedia method for a list and description of valid sound emitter states. The number of seconds of audio that have completed is returned. For streaming emitters this value is a cumulative value and for cached emitters this value is reset to 0.0 at the end of each loop. To convert to position in milliseconds, multiply the position in seconds by 1000. For cached emitters the total length of the file in seconds and the number of loops that have been completed are also returned. This function also returns the audibility level of an emitter.

Usage Sample

// Everytime the timer fires we update
// the mediastate, play time, etc.
void CMainWindow::OnTimer(UINT nIDEvent) 
{
    RSXQUERYMEDIAINFO qmi;
    
    qmi.cbSize = sizeof(RSXQUERYMEDIAINFO);
    m_lpCE->QueryMediaState(&qmi);

    CDC* pDC = GetDC();
    
    char data[256];
    CString szControlCode;

    // What state is the emitter in??
    switch(qmi.dwControl){
        case RSX_PLAY:
    	    szControlCode = "RSX_PLAY";
	    break;
        case RSX_PAUSE:
	        szControlCode = "RSX_PAUSE";
	    break;
        case RSX_STOP:
	        szControlCode = "RSX_STOP";
	    break;
        case RSX_RESUME:
	        szControlCode = "RSX_RESUME";
	    break;
        default:
	        szControlCode = "UNKNOWN PLAY STATE";
	    break;
    } /* switch */

    pDC->TextOut(0,0,szControlCode);
    
    // How many seconds of the file have been played
    // This resets to zero everytime the Endmark position
    // is reached. It also takes into consideration the
    // Startmark position.  Thus if the mark positions
    // are StartMark = 2.0s, EndMark = 4.0s the seconds
    // played will cycle from 0 to 2 seconds
    sprintf(data,"fSecondsPlayed = %f", qmi.fSecondsPlayed);
    pDC->TextOut(0,30,data);

    // The total length of the wave file
    sprintf(data,"fTotalSeconds = %f", qmi.fTotalSeconds);
    pDC->TextOut(0,60,data);

    // How many loops have we completed
    sprintf(data,"dwNumLoops = %d", qmi.dwNumLoops);
    pDC->TextOut(0,90,data);

    // What is our audible level
    sprintf(data,"fAudiblelevel = %f",qmi.fAudibleLevel);
    pDC->TextOut(0,120,data);

    ReleaseDC(pDC);

} /* OnTimer */


SetCPUBudget

Overrides the environment processing budget for this specific emitter.

HRESULT SetCPUBudget(CPUBudget)

Parameters

RSX_CPU_Budget CPUBudget
Specifies the processing budget for audio localization quality.

Returns

S_OK
E_INVALIDARG
E_NOTIMPL

Description

The processing budget value for a single emitter can be different from the application-wide processing budget specified by the SetEnvironment method.

RSX uses the processing budget value as a guide when it determines to what extent it must localize a specific sound. The higher the budget, the better the audio localization quality. Valid choices are RSX_MIN_BUDGET, RSX_LOW_BUDGET, and RSX_MODERATE_BUDGET. The selection of RSX_MIN_BUDGET can be used to play a standard ambient sound.

NOTE. RSX 3D does not currently support GetCPUBudget and SetCPUBudget.

See Also

GetCPUBudget

SetModel

Updates the emitter's model parameters.

HRESULT SetModel(lpEmitterModel);

Parameters

LPRSXEMITTERMODEL lpEmitterModel
Pointer to a RSXEMITTERMODEL that contains the new emitter's model parameters.
 

Returns

S_OK
E_INVALIDARG

Description

The emitter's model parameters describe the front and back ranges for the ambient and attenuation regions of the RSX sound model. Adjusting the ratio of front to back varies the emitter's directionality.

Usage Sample

/*
// Set the emitter model
*/
RSXEMITTERMODEL rsxEModel;
rsxEModel.cbSize = sizeof(RSXEMITTERMODEL);

// This defines the inner ellipsoid of the 
// emitter.  Sound is ambient in this region.
rsxEModel.fMinFront = 1.0f;
rsxEModel.fMinBack = 1.0f;

// This defines the outer ellipsoid of the emitter.
// Sound is localized between the edge of the inner
// ellipsoid and the outer ellipse. If the listener position 
// is outside of this ellipsoid, the emitter cannot be heard. 
rsxEModel.fMaxFront = 20.0f;
rsxEModel.fMaxBack  = 20.0f;

// The intensity (volume) of the emitter.
// Generally between 0.00f and 1.00f.
rsxEModel.fIntensity = 0.7f;                

// Actually set the model
m_lpCE->SetModel(&rsxEModel);
. . .

See Also

GetModel

SetMuteState

Sets the mute state of the emitter.

HRESULT SetMuteState(dwMuteState)

Parameters

DWORD dwMuteState

Specifies the mute state for the emitter. A non-zero value indicates the emitter is muted and therefore will not be audible. Zero indicates the emitter is not muted and may be audible.

Returns

S_OK

Description

When an emitter is muted, it still maintains the correct play position. If you would like to freeze the current play position for a cached emitter, you should use RSX_PAUSE when calling the IRSXCachedEmitter Interface's ControlMedia method.

Usage Sample

// Muting the emitter keeps the file pointer moving
// in time on the wave file but you cannot hear the
// sound. 
void CMainWindow::OnFileMute() 
{
    m_lpCE->SetMuteState(1);
} 

// Unmute the emitter so we can hear it
void CMainWindow::OnFileUnmute() 
{
    m_lpCE->SetMuteState(0);
}  

See Also

GetMuteState

SetOrientation

Specifies a 3D vector that points in the same direction as the emitter's orientation.

HRESULT SetOrientation(lpOrientation)

Parameters

LPRSXVECTOR3D lpOrientation
Pointer to a RSXVECTOR3D data structure containing the emitter's new orientation vector.

Returns

S_OK
E_INVALIDARG
RSXERR_ZEROVECTOR

Description

This method sets the direction vector for either a cached or streaming emitter.

Usage Sample

// Point the emitter along the Z axis.

RSXVECTOR3D v3d;
v3d.x = 0.0f
v3d.y = 0.0f;
v3d.z = 1.0f;
m_lpCE->SetOrientation(&v3d);
. . .

See Also

GetOrientation

SetPitch

Specifies the pitch adjustment of the emitter.

HRESULT SetPitch(fPitch)
 

Parameters

FLOAT fPitch
Specifies the emitter's pitch adjustment. A factor of 1.0 plays the emitter at the normal pitch. The valid range is from 0.25 to 4.0.

Returns

S_OK
E_INVALIDARG

Description

Pitch is the height or depth of a tone. The SetPitch method alters the tone of an emitter. The default pitch factor is 1.0 which indicates no change in tone. A pitch of 0.25 indicates a low depth of tone, whereas a pitch of 4.0 indicates a high, shrill tone. When an emitter's pitch changes, its timing also changes in proportion to the pitch.

Usage Sample

/*
// Set the pitch value to 2.5
*/

FLOAT fPitch=2.5;
m_lpCE->SetPitch(fPitch);
. . .

See Also

GetPitch

SetPosition

Sets the X,Y,Z coordinates of the emitter.

HRESULT SetPosition(lpPosition)
 

Parameters

LPRSXVECTOR3D lpPosition
Pointer to a RSXVECTOR3D data structure containing the emitter's new position.

Returns

S_OK
E_INVALIDARG

Description

Position describes the emitter's location in the 3D audio environment.

Usage Sample

// Move the emitter to our left
void CMainWindow::OnControlLeft() 
{
    RSXVECTOR3D v3d;
    v3d.x = -5.0f;
    v3d.y = 0.0f;
    v3d.z = 0.0f;
    m_lpCE->SetPosition(&v3d);
}

// Move to emitter to our right
void CMainWindow::OnControlRight() 
{
    RSXVECTOR3D v3d;
    v3d.x = 5.0f;
    v3d.y = 0.0f;
    v3d.z = 0.0f;
    m_lpCE->SetPosition(&v3d);
}

See Also

GetPosition

IRSXCachedEmitter

The IRSXCachedEmitter contains the methods defined by the IRSXEmitter abstract base class and the following additional methods:

IRSXCached Emitter Methods and Meaning

ControlMedia
Provides VCR-like control for a cached emitter.
 
GetCacheTime
Retrieves the pre-load length for the emitter's file.
 
GetMarkPosition
Retrieves the begin and end playback marks.
 
Initialize
Initializes the cached emitter for use.
 
SetCacheTime
Sets the pre-load length for the emitter's file.
 
SetMarkPosition
Sets the begin and end playback marks.

ControlMedia

Performs standard media control functions on the cached sound emitter.

HRESULT ControlMedia(dwControl, nLoops, fInitialStartTime);

Parameters

DWORD dwControl
Specifies the type of control operation to perform on the sound emitter. It must be one of the following values:
Value and Meaning
RSX_PLAY
Start playing sound from the specified starting position and continue until the specified ending position for the number of iterations specified by nLoops. When the sound has completed, the emitter will be placed in the RSX_STOP state and the event specified when the emitter was created will be signaled.
 
RSX_PAUSE
Stop playing the sound, but do not reset the sound's play position.
 
RSX_RESUME
Continue playing the sound from the last paused position.
 
RSX_STOP
Stop the sound regardless of state. The event specified when the emitter was created will be signaled
DWORD nLoops
Specifies the number of loops to play, at the positions indicated by the IRSXCachedEmitter Interface's SetMarkPosition method. Zero indicates continuous looping. This parameter only applies when the RSX_PLAY control is specified.
 
FLOAT fInitialStartTime
Specifies the starting position, in seconds, from the beginning of the file for the first loop of playback. This parameter only applies when the RSX_PLAY control is specified.

Returns

S_OK
E_INVALIDARG
E_FAIL

Description

You can use this method to specify play positions and to control the number of loops to play. You can play, pause, or restart audio at any time during a cached emitter's lifetime. The play positions are specified in seconds, using floating-point precision. These positions are rounded to the nearest sample. To convert to position in milliseconds, multiply the position in seconds by 1000.

Usage Sample

// Pause the emitter
void CMainWindow::OnControlPause() 
{
    m_lpCE->ControlMedia(RSX_PAUSE, 0, 0.0f);
}

// Begin playing the emitter
void CMainWindow::OnControlPlay() 
{
    m_lpCE->ControlMedia(RSX_PLAY, dlg.m_nLoops, dlg.m_fInitStart);
}

// Stop playback of the emitter
void CMainWindow::OnControlStop() 
{
    m_lpCE->ControlMedia(RSX_STOP, 0, 0.0f);
}

// Resume playing from a paused state.
// This does nothing if the emitter is currently playing or stopped.  
// The emitter must be paused for resume to take effect.
void CMainWindow::OnControlResume() 
{
    m_lpCE->ControlMedia(RSX_RESUME, 0, 0.0f);
}

GetCacheTime

Retrieves the pre-load length for the emitter's file.

HRESULT GetCacheTime(lpfCacheTime)

Parameters

PFLOAT lpfCacheTime
Pointer to a FLOAT-sized location to be filled with the pre-load length in seconds.

Returns

S_OK
E_INVALIDARG

Description

RSX 3D uses a default cache time of approximately three seconds. The maximum cache time depends on the available system memory.

Usage Sample

/*
// Get the cache time
*/
FLOAT fCacheTime;
m_lpCE->GetCacheTime(&fCacheTime);
. . .

See Also

SetCacheTime

GetMarkPosition

GetMarkPosition retrieves the begin and end playback mark.

HRESULT GetMarkPosition(lpfBeginTime, lpfEndTime);

Parameters

PFLOAT lpfBeginTime
Pointer to a FLOAT-sized location to be filled with the starting position in seconds for emitter playback within the file. Zero indicates the starting position is the file's beginning.
 
PFLOAT lpfEndTime
Pointer to a FLOAT-sized location to be filled with the ending position in seconds for emitter playback within the file. Zero indicates the ending position of the file.

Returns

S_OK
E_INVALIDARG

Description

The start position and end position identify offsets in a circular buffer. By default, these values are zero, indicating the entire file should be played. The end position must be greater than the start position.

Usage Sample

// Get the default mark positions
// When playing, the CachedEmitter will
// loop from the starting mark position to 
// the ending mark position.
// This is useful if you want to play a segment
// of a WAVE file, i.e. begin at 10 seconds, end at 15 seconds
*/
FLOAT fStartMark, fEndMark;    
m_lpCE->GetMarkPosition(&fStartMark, &fEndMark);
. . .

See Also

SetMarkPosition

Initialize

Initialize initializes the cached emitter for use.

HRESULT Initialize(lpCachedEmitterAttr, pUnk);

Parameters

LPRSXCACHEDEMITTERDESC lpCachedEmitterAttr
Pointer to an RSXCACHEDEMITTERDESC data structure that specifies the filename of the sound the emitter will play.
 
LPUNKNOWN pUnk
IUnknown pointer to an RSX20 object. Obtain this pointer through a call to CoCreateInstance or QueryInterface.
For more details.

Returns

S_OK
E_INVALIDARG
E_OUTOFMEMORY
E_FAIL
RSXERR_FILENOTFOUND
RSXERR_FILESHARINGVIOLATION
RSXERR_CORRUPTFILE

Description

This function must be called before any other functions in the IRSXCachedEmitter interface. Only call this function once during the lifetime of a cached emitter. Subsequent calls to the function will fail.

Usage Sample

	RSXCACHEDEMITTERDESC rsxCE;             // emitter description
		
	ZeroMemory(&rsxCE, sizeof(RSXCACHEDEMITTERDESC));
	rsxCE.cbSize = sizeof(RSXCACHEDEMITTERDESC);
	rsxCE.dwFlags = 0;
	rsxCE.dwUser = 50;

	// If you want to use a wave file embedded as a resource 
	// instead of a file replace "cppmin.wav" with "cppmin.exe RESOURCE_ID"
	// i.e. "cppmin.exe 15" or try this:
	// sprintf(aeDesc.szFilename,"cppmin.exe %d", IDR_WAVE1);
	//
	// OR if you have installed Microsoft Internet Explorer 3.0
	// and it is configured correctly you
	// can use an URL-based emitter like:
	// http://www.junk.com/mywaves/cppmin.wav
	// or
	// ftp:://ftp.junk.com/waves/cppmin.wav
	//
	strcpy(rsxCE.szFilename,"cppmin.wav");

	// initialize the CachedEmitter and 'attach' it to 
	// the same RSX20 object as the DirectListener
	// otherwise we won't hear anything
	hr = m_lpCE->Initialize(&rsxCE, m_lpUnk);
. . .

SetCacheTime

Sets pre-load length for the emitter's file.

HRESULT SetCacheTime(fCacheTime)

Parameters

FLOAT fCacheTime
Specifies the pre-load length seconds.

Returns

S_OK
E_INVALIDARG

Description

The maximum cache time depends on available system memory. If the application requests a cache time that is too large or too small, the E_INVALIDARG error code will be returned. The default cache time used by RSX 3D is approximately three seconds, although this value can be modified in the registry using the configuration tool (RSXConfg.exe). Valid cache times are greater than or equal to 1.0 seconds.

Usage Sample

// Set mark positions, cached time, etc.
void CMainWindow::OnControlSettings() 
{
    DWORD result = dlg.DoModal();
	
	if(result == IDOK) {
    	m_lpCE->SetMarkPosition(dlg.m_fStartMark, dlg.m_fEndMark);
    	m_lpCE->SetCacheTime(dlg.m_fCacheTime);
	OnControlPlay();
    } /* if */
}

See Also

GetCacheTime

SetMarkPosition

Sets the begin and end playback mark.

HRESULT SetMarkPosition(fBeginTime, fEndTime)
 

Parameters

FLOAT fBeginTime
Marks the starting position, in seconds, for emitter playback within the file. Zero indicates the starting position is the file's beginning.
 
FLOAT fEndTime
Marks the ending position, in seconds, for emitter playback within the file. Zero indicates the ending position of the file.

Returns

S_OK
E_INVALIDARG

Description

Marks the starting and ending position for playback of a cached emitter. The start position must be less than the end position. By default, these values are zero, indicating the entire file should be played.

Usage Sample

// Set mark positions, cached time, etc.
void CMainWindow::OnControlSettings() 
{
    DWORD result = dlg.DoModal();
	
	if(result == IDOK) {
    	m_lpCE->SetMarkPosition(dlg.m_fStartMark, dlg.m_fEndMark);
    	m_lpCE->SetCacheTime(dlg.m_fCacheTime);
	OnControlPlay();
    } /* if */
}

See Also

GetMarkPosition

RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Copyright ©1996, 1997 Intel Corporation. All rights reserved