RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Interfaces

IRSXStreamingEmitter

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

IRSXStreamingEmitter Methods and Meaning

Flush
Returns all submitted buffers, removing them from the emitter's playback queue.
 
Initialize
Initializes the streaming emitter for use.
 
SubmitBuffer
Writes a buffer to the emitter's playback queue.

Flush

Requests the immediate return of all buffers in the emitter'splayback queue and resets the playback position to zero.

HRESULT Flush()

Returns

S_OK

Description

This function returns after all events have been signaled.

Usage Sample

case START_EVENT:{
                  // This is an event we signal from
                  // our OnPlay() function which is called
                  // when the user selects the Play Option from the 
                  // menu

                  // First we flush our streaming emitter to make
                  // sure that old data is not in the buffer Queue
                  pThis->m_lpSE->Flush();

                  dwState = PLAY_STATE;
                  . . .    

Initialize

Initialize initializes the streaming emitter for use.

HRESULT Initialize(lpStreamingEmitterAttr, pUnk);

Parameters

LPRSXSTREAMINGEMITTERDESC lpStreamingEmitterAttr
Pointer to an RSXSTREAMINGEMITTERDESC that specifies the format of the buffers to be streamed by the emitter.
 
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_FAIL
E_INVALIDARG
E_OUTOFMEMORY
RSXERR_BADFORMAT

Description

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

Usage Sample


	RSXSTREAMINGEMITTERDESC seDesc;
	memset(&seDesc, 0, sizeof(RSXSTREAMINGEMITTERDESC));
	seDesc.cbSize = sizeof(RSXSTREAMINGEMITTERDESC);

	seDesc.lpwf = new WAVEFORMATEX;
	if(!seDesc.lpwf) {
		return 0;
	}

	// fill in the waveformat with values
	// for 22kHz, 16-bit, mono, PCM format
	seDesc.lpwf->wFormatTag = WAVE_FORMAT_PCM;
	seDesc.lpwf->nChannels = 1;
	seDesc.lpwf->nSamplesPerSec = 22050;
	seDesc.lpwf->nAvgBytesPerSec = 44100;
	seDesc.lpwf->nBlockAlign = 2;
	seDesc.lpwf->wBitsPerSample = 16;
	seDesc.lpwf->cbSize = 0;

	hr = m_lpSE->Initialize(&seDesc, m_lpUnk);
. . .

SubmitBuffer

Writes a buffer to the emitter's queue for playback.

HRESULT SubmitBuffer(lpBufferHdr)

Parameters

LPRSXBUFFERHDR lpBufferHdr
Pointer to a RSXBUFFERHDR containing buffer to be played.

Returns

S_OK
E_INVALIDARG

Description

This function is non-blocking.

The number of bytes submitted must be a multiple of the nBlockAlign field of the WAVEFORMATEX structure specified at emitter creation time. This prevents partial samples from being submitted.

Usage Sample

case START_EVENT:{
                  // This is an event we signal from
                  // our OnPlay() function which is called
                  // when the user selects the Play Option from the 
                  // menu.

                  // First we flush our streaming emitter to make
                  // sure that old data is not in the buffer Queue
                  pThis->m_lpSE->Flush();

                  dwState = PLAY_STATE;

                  // Now we prefill our first two buffers
                  // In this sample we just keep sending the same
                  // buffers over and over (a sine wave)
                  // We could have done this initialization
                  // in the InitializeAudio function
                  // but in the general case it is better
                  // to do it on this thread as most apps
                  // will do more interesting things
                  // then send the same buffers down, over and over.
               
                  //PFLOAT pD = (PFLOAT)&(pThis->m_Data);
                  short int* pD = (short int*)&(pThis->m_Data);

                  // generate a sine wave and fill up m_Data
                  for(i = 0; i < NUM_SAMPLES; i++) {
                      *pD++ = (short int)(sin(2 * 3.14159 * i * 
                               296.0815 / 22050.0) * 5000.0);
                  } /* for */
                        
                  // Now we submit both buffers
                  pThis->m_lpSE->SubmitBuffer(&pThis->m_Buffer1);
                  pThis->m_lpSE->SubmitBuffer(&pThis->m_Buffer2);

                  break;
              }
              case STOP_EVENT:
                  // This is an event we signal from
                  // our OnStop() function which is called
                  // when the user selects the Stop Option from the 
                  // menu
                
                  // First we flush our streaming emitter to 
                  // immediately stop playback
                  pThis->m_lpSE->Flush();

                  // Now we put ourselves into the STOP_STATE
                  // This is so we don't sent any more buffers until
                  // we return to the PLAY_STATE
                  dwState = STOP_STATE;

                  break;

IRSXListener Abstract Base Class

The IRSXListener is an abstract base class defining the general characteristics of audio listeners. This interface controls the position and orientation of the listener in the audio environment. The supported listener types, IRSXDirectListener and IRSXStreamingListener, provide this functionality through their interfaces.

NOTE: An application cannot use the IRSXListener interface directly. It is encapsulated as part of a specific listener, such as the IRSXDirectListener or the IRSXStreamingListener.

IRSXListener Abstract Base Class Methods and Meaning

GetOrientation
Retrieves the listener's orientation in 3D space.
 
GetPosition
Retrieves the listener's position in 3D space.
 
GetUserData
Retrieves the user data for the listener.
 
SetOrientation
Orients the listener in 3D space.
 
SetPosition
Positions the listener in 3D space.

GetOrientation

Retrieves the pair of 3D vectors that points in the listener's orientation and up directions.

HRESULT GetOrientation(lpDirection, lpUp)

Parameters

LPRSXVECTOR3D lpDirection
Pointer to a RSXVECTOR3D that will be filled with the listener's direction vector.
 
LPRSXVECTOR3D lpUp
Pointer to a RSXVECTOR3D that will be filled with the listener's up vector.

Returns

S_OK
E_INVALIDARG

Description

This method retrieves the direction and up vectors for either a direct or streaming listener.

Usage Sample

// This is how to retrieve the listener's 
// orientation
RSXVECTOR3D v3d;
RSXVECTOR3D v3d2;
m_lpDL->GetOrientation(&v3d, &v3d2);
. . .

See Also

SetOrientation

GetPosition

Retrieves the X,Y,Z coordinates of the audio listener.

HRESULT GetPosition(lpPosition)

Parameters

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

Returns

S_OK
E_INVALIDARG

Description

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

Usage Sample

// This is how to retrieve the listener's 
// position 
RSXVECTOR3D v3d;        
m_lpDL->GetPosition(&v3d);
. . .

See Also

SetPosition

GetUserData

Retrieves the user-defined data for the listener.

HRESULT GetUserData(lpdwUser)

Parameters

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

Returns

S_OK
E_INVALIDARG

Description

User defined data is a 32-bit location that is useful for storing pointers to other data structures.

Usage Sample

// This is how to retrieve your user data.
// User data is useful for storing pointers to other data
// structures useful in your application
        DWORD dwUser;
        m_lpDL->GetUserData(&dwUser);
        . . .

SetOrientation

Specifies a pair of 3D vectors that point in the listener's orientation and up direction.

HRESULT SetOrientation(lpDirection, lpUp)

Parameters

LPRSXVECTOR3D lpDirection
Pointer to a RSXVECTOR3D containing the listener's new direction vector.
 
LPRSXVECTOR3D lpUp
Pointer to a RSXVECTOR3D containing the listener's new up vector.

Returns

S_OK
E_INVALIDARG
RSXERR_PARALLELVECTORS
RSXERR_ZEROVECTOR

Description

This method sets the direction and up vectors for a listener. It returns an error if the direction and up vectors are parallel. If the direction and up vectors are not perpendicular, the up vector will be calculated assuming that the direction vector is correct.

Usage Sample

//
// Listener orientation settings
// This vector is the direction the listener is facing
RSXVECTOR3D v3dorient;
v3dOrient.x = 0.0f;
v3dOrient.y = 0.0f;
v3dOrient.z = 1.0f;
 
// "up" vector - perpendicular to orientation vector
// This vector points to which direction is up for the listener -
// it can not be parallel to the listener orientation vector
RSXVECTOR3D v3dorient;
v3dUpOrient.x = 0.0f;
v3dUpOrient.y = 1.0f;
v3dUpOrient.z = 0.0f;
// Set the orientation of the listener
m_lpDL->SetOrientation(&v3dOrient, &v3dUpOrient);
. . .

 

See Also

GetOrientation

SetPosition

Sets the X,Y,Z coordinates of the audio listener.

HRESULT SetPosition(lpPosition)

Parameters

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

Returns

S_OK
E_INVALIDARG

Description

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

Usage Sample

//
// Set the direct listener's or streaming listener's position
RSXVECTOR3D v3d;        
v3d.x = 0.0f;
v3d.y = 0.0f;
v3d.z = 0.0f;
m_lpDL->SetPosition(&v3d);
. . .

See Also

GetPosition
 

IRSXDirectListener

The IRSXDirectListener interface contains the methods defined by the IRSXListener abstract base class and the following additional methods:

IRSXDirectListener Methods and Meaning

Connect
Reattaches the listener's connection to the previously connected output device resource.
 
Disconnect
Detaches the listener from the output device resource so another client can access the output device.
Initialize
Initializes the direct listener for use.

Connect

Reattaches the listener to the previously connected output device resource.

HRESULT Connect()

Returns

S_OK
E_FAIL
RSXERR_ALLOCATED

Description

Connect allows you to attach or reattach the direct listener to the output device resource. The output device resource can be either DirectSound II (or later) or Wave API.

Usage Sample

// This connects the DirectListener if it was
// disconnected
void CMainWindow::OnFileConnect() 
{
        m_lpDL->Connect();

} /* Connect */
. . .      

Disconnect

Detaches the listener from the output device resource.

HRESULT Disconnect()

Returns

S_OK
E_FAIL

Description

Disconnect allows you to detach the direct listener from the output device resource. The output device resource can be either DirectSound II (or later) or Wave API.

Usage Sample

//
// This Disconnects the DirectListener.
// This is useful if you want to temporarily disable
// RSX from using the audio device so another application
// can play audio and/or to allow input (through a microphone...)
void CMainWindow::OnFileDisconnect() 
{
        m_lpDL->Disconnect();   

} /* Disconnect */

Initialize

Initialize initializes the direct listener for use.

HRESULT Initialize(lpDirectListenerAttr, pUnk);

Parameters

LPRSXDIRECTLISTENERDESC lpDirectListenerAttr
Pointer to an RSXDIRECTLISTENERDESC that provides reference information about the direct listener object.
 
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_FAIL
E_INVALIDARG
E_OUTOFMEMORY
RSXERR_BADFORMAT
RSXERR_ALLOCATED
RSXERR_NODRIVER

Description

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

Usage Sample

// Initialize a Direct Listener
RSXDIRECTLISTENERDESC rsxDL;

// listener description
rsxDL.cbSize = sizeof(RSXDIRECTLISTENERDESC);
rsxDL.hMainWnd = AfxGetMainWnd()->GetSafeHwnd();
rsxDL.dwUser = 0;
rsxDL.lpwf = NULL;

// create the direct listener now
m_lpDL>Initialize(&rsxDL, m_lpUnk);
...


IRSXStreamingListener

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

IRSXStreamingListener Methods and Meaning

Initialize
Initializes the streaming listener for use.
 
RequestBuffer
Requests the synchronous generation of audio output.

Initialize

Initialize initializes the streaming listener for use.

HRESULT Initialize(lpStreamingListenerAttr, pUnk);

Parameters

LPRSXSTREAMINGLISTENERDESC lpStreamingListenerAttr
Pointer to an RSXSTREAMINGLISTENERDESC that provides reference information about the streaming listener object.
 
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_FAIL
E_INVALIDARG
E_OUTOFMEMORY
RSXERR_BADFORMAT

Description

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

Usage Sample

/*
// Initialize streaming listener
//
// Fill WAVEFORMATEX structure to specify output format
// Fill RSXSTREAMINGLISTENERDESC to specify listener creation settings
*/
m_wfx.wFormatTag = WAVE_FORMAT_PCM;
m_wfx.nChannels = 2;
m_wfx.nSamplesPerSec = 22050;
m_wfx.nAvgBytesPerSec = 88200;
m_wfx.nBlockAlign = 4;
m_wfx.wBitsPerSample = 16;
m_wfx.cbSize = 0;

DWORD dwListenerBufferSizeInMS = 200; //Lets try 200ms buffers in
//this example
RSXSTREAMINGLISTENERDESC slDesc;

slDesc.cbSize = sizeof(RSXSTREAMINGLISTENERDESC);
slDesc.dwRequestedBufferSize =
dwListenerBufferSizeInMS * m_wfx.nAvgBytesPerSec / 1000;
slDesc.lpwf = &m_wfx;
slDesc.dwUser = 0;

m_lpSE->Initialize(&slDesc, m_lpUnk)_;
. . .


RequestBuffer

Requests the synchronous generation of a buffer of audio data.

HRESULT RequestBuffer (lpBufferA, lpBufferB, dwSizeB)

Parameters

LPSTR lpBufferA
Pointer to first buffer to be filled.
 
LPSTR lpBufferB
Pointer to second buffer to be filled.
 
DWORD dwSizeB
Size in bytes of the second buffer.

Returns

S_OK
E_INVALIDARG

Description

The lpBufferB and dwSizeB parameters simplify using RSX 3D when circular buffers are used. For standard, single buffer requests, lpBufferB should be NULL.

This function is not interrupt safe.

Usage Sample

/*
// Request Buffer Sample
*/
LRESULT 
CMainWindow::OnWOMDone(WPARAM w, LPARAM l)
{
        LPWAVEHDR lpWaveHdr = (LPWAVEHDR )l;
        if(m_bInShutdown){

                                /*
                // We are closing down shop, rather than resubmit, 
                // just unprepare it.
                */
                waveOutUnprepareHeader( m_hWaveOut, lpWaveHdr,
                                    sizeof(WAVEHDR));
                HeapFree(m_hBufferHeap, 0, lpWaveHdr->lpData);
                HeapFree(m_hBufferHeap, 0, lpWaveHdr);

        } else {
        /*
        // Request buffer from streaming listener and fill WAVEHDR lpData
        */
        m_lpSL->RequestBuffer(lpWaveHdr->lpData, NULL, 0);

                /*
                // Send it back to the wave device with fresh samples 
                // for playback
                */
           if(MMSYSERR_NOERROR != waveOutWrite(m_hWaveOut, lpWaveHdr,                              sizeof(WAVEHDR))) {
                        AfxMessageBox("waveOutWrite failed");
                } /* if        */
        } /* if */
        return 0;
} 

RSX 3D  Contents  Interfaces  Data Structures  Previous  Next

Copyright ©1996, 1997 Intel Corporation. All rights reserved