RSX 3D Contents Interfaces Data Structures Previous Next
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.
Retrieves the emitter's processing budget.
Syntax
HRESULT GetCPUBudget(lpCPUBudget)
Parameters
Returns
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
NOTE. RSX 3D does not currently support GetCPUBudget and SetCPUBudget.
Retrieves the emitter's model parameters.
HRESULT GetModel(lpEmitterModel)
Parameters
Returns
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
Retrieves the mute state of the emitter.
HRESULT GetMuteState (lpdwMuteState)
Parameters
Returns
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
Retrieves a 3D vector that points in the same direction as the emitter's orientation.
HRESULT GetOrientation(lpOrientation)
Parameters
Returns
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
Retrieves the pitch adjustment of the emitter.
HRESULT GetPitch(lpfPitch)
Parameters
Returns
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
Retrieves the X,Y,Z coordinates of the emitter.
HRESULT GetPosition(lpPosition)
Parameters
Returns
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
Retrieves the user-defined data for the emitter.
HRESULT GetUserData(lpdwUser)
Parameters
Returns
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); . . .
Queries the state of the emitter.
HRESULT QueryMediaState(lpQueryMediaInfo)
Parameters
Returns
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 */
Overrides the environment processing budget for this specific emitter.
HRESULT SetCPUBudget(CPUBudget)
Parameters
Returns
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
Updates the emitter's model parameters.
HRESULT SetModel(lpEmitterModel);
Parameters
Returns
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
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
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
Specifies a 3D vector that points in the same direction as the emitter's orientation.
HRESULT SetOrientation(lpOrientation)
Parameters
Returns
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
Specifies the pitch adjustment of the emitter.
HRESULT SetPitch(fPitch)
Parameters
Returns
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
Sets the X,Y,Z coordinates of the emitter.
HRESULT SetPosition(lpPosition)
Parameters
Returns
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
The IRSXCachedEmitter contains the methods defined by the IRSXEmitter abstract base class and the following additional methods:
Performs standard media control functions on the cached sound emitter.
HRESULT ControlMedia(dwControl, nLoops, fInitialStartTime);
Parameters
- 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
Returns
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); }
Retrieves the pre-load length for the emitter's file.
HRESULT GetCacheTime(lpfCacheTime)
Parameters
Returns
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
GetMarkPosition retrieves the begin and end playback mark.
HRESULT GetMarkPosition(lpfBeginTime, lpfEndTime);
Parameters
Returns
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
Initialize initializes the cached emitter for use.
HRESULT Initialize(lpCachedEmitterAttr, pUnk);
Parameters
Returns
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); . . .
Sets pre-load length for the emitter's file.
HRESULT SetCacheTime(fCacheTime)
Parameters
Returns
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
Sets the begin and end playback mark.
HRESULT SetMarkPosition(fBeginTime, fEndTime)
Parameters
Returns
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
RSX 3D Contents Interfaces Data Structures Previous Next
Copyright ©1996, 1997 Intel Corporation. All rights reserved