Base class for sound streams
Derived from
No base class
Include files
<wx/mmedia/sndbase.h>
Data structures
wxSoundStream errors
wxSOUND_NOERR | No error occurred |
wxSOUND_IOERR | An input/output error occurred, it may concern either a driver or a file |
wxSOUND_INVFRMT | The sound format passed to the function is invalid. Generally, it means that you passed out of range values to the codec stream or you don't pass the right sound format object to the right sound codec stream. |
wxSOUND_INVDEV | Invalid device. Generally, it means that the sound stream didn't manage to open the device driver due to an invalid parameter or to the fact that sound is not supported on this computer. |
wxSOUND_NOEXACT | No exact matching sound codec has been found for this sound format. It means that the sound driver didn't manage to setup the sound card with the specified values. |
wxSOUND_NOCODEC | No matching codec has been found. Generally, it may happen when you call wxSoundRouterStream::SetSoundFormat(). |
wxSOUND_MEMERR | Not enough memory. |
C callback for wxSound event
When a sound event is generated, it may either call the internal sound event processor (which can be inherited) or call a C function. Its definition is:
typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt, void *cdata);The stream parameter represents the current wxSoundStream.
The evt parameter represents the sound event which is the cause of the calling. (See wxSound events).
The cdata parameter represents the user callback data which were specified when the user called wxSoundStream::Register.
Note: There are two other ways to catch sound events: you can inherit the sound stream and redefine wxSoundStream::OnSoundEvent, or you can reroute the events to another sound stream using wxSoundStream::SetEventHandler.
wxSound streaming mode
The wxSoundStream object can work in three different modes. These modes are specified at the call to wxSoundStream::StartProduction and cannot be changed until you call wxSoundStream::StopProduction.
The wxSOUND_INPUT mode is the recording mode. It generates wxSOUND_INPUT events and you cannot use wxSoundStream::Write().
The wxSOUND_OUTPUT mode is the playing mode. It generates wxSOUND_OUTPUT events and you cannot use wxSoundStream::Read().
The wxSOUND_DUPLEX mode activates the full duplex mode. The full duplex requires you to make synchronous call to wxSoundStream::Read and wxSoundStream::Write. This means that you must be careful with realtime problems. Each time you call Read you must call Write.
wxSoundStream events
The sound events are generated when the sound driver (or the sound stream) completes a previous sound buffer. There are two possible sound events and two meanings.
The wxSOUND_INPUT event is generated when the sound stream has a new input buffer ready to be read. You know that you can read a buffer of the size GetBestSize() without blocking.
The wxSOUND_OUTPUT event is generated when the sound stream has completed a previous buffer. This buffer has been sent to the sound driver and it is ready to process a new buffer. Consequently, Write will not block too.
Members
wxSoundStream::wxSoundStream
wxSoundStream::~wxSoundStream
wxSoundStream::Read
wxSoundStream::Write
wxSoundStream::GetBestSize
wxSoundStream::SetSoundFormat
wxSoundStream::GetSoundFormat
wxSoundStream::SetCallback
wxSoundStream::StartProduction
wxSoundStream::StopProduction
wxSoundStream::SetEventHandler
wxSoundStream::GetError
wxSoundStream::GetLastAccess
wxSoundStream::QueueFilled
wxSoundStream::OnSoundEvent
wxSoundStream()
Default constructor.
~wxSoundStream()
Destructor. The destructor stops automatically all started production and destroys any temporary buffer.
wxSoundStream& Read(void* buffer, wxUint32 len)
Reads len bytes from the sound stream. This call may block the user so use it carefully when you need to intensively refresh the GUI. You may be interested by sound events: see wxSoundStream::OnSoundEvent.
It is better to use the size returned by wxSoundStream::GetBestSize: this may improve performance or accuracy of the sound event system.
Parameters
len
data
wxSoundStream& Write(const void* buffer, wxUint32 len)
Writes len bytes to the sound stream. This call may block the user so use it carefully. You may be interested by sound events: see wxSoundStream::OnSoundEvent.
It is better to use the size returned by wxSoundStream::GetBestSize: this may improve performance or accuracy of the sound event system.
Parameters
len
buffer
wxUint32 GetBestSize() const
This function returns the best size for IO calls. The best size provides you a good alignment for data to be written (or read) to (or from) the sound stream. So, when, for example, a sound event is sent, you are sure the sound stream will not block for this buffer size.
bool SetSoundFormat(const wxSoundFormatBase& format)
SetSoundFormat is one of the key function of the wxSoundStream object. It specifies the sound format the user needs. SetSoundFormat tries to apply the format to the current sound stream (it can be a sound file or a sound driver). Then, either it manages to apply it and it returns TRUE, or it could not and it returns FALSE. In this case, you must check the error with wxSoundStream::GetError. See wxSoundStream errors section for more details.
Note
The format object can be destroyed after the call. The object does not need it.
Note
If the error is wxSOUND_NOTEXACT, the stream tries to find the best approaching format and setups it. You can check the format which it applied with wxSoundStream::GetSoundFormat.
It returns a reference to the current sound format of the stream represented by a wxSoundFormatBase object. This object must not be destroyed by anyone except the stream itself.
void Register(int evt, wxSoundCallback cbk, void* cdata)
It installs a C callback for wxSoundStream events. The C callbacks are still useful to avoid hard inheritance. You can install only one callback per event. Each callback has its callback data.
bool StartProduction(int evt)
StartProduction starts the sound streaming. evt may be one of wxSOUND_INPUT, wxSOUND_OUTPUT or wxSOUND_DUPLEX. You cannot specify several flags at the same time. Starting the production may automaticaly in position of buffer underrun (only in the case you activated recording). Actually this may happen the sound IO queue is too short. It is also advised that you fill quickly enough the sound IO queue when the driver requests it (through a wxSoundEvent).
bool StopProduction()
I stops the async notifier and the sound streaming straightly.
void SetEventHandler(wxSoundStream* handler)
Sets the event handler: if it is non-null, all events are routed to it.
wxSoundError GetError() const
It returns the last error which occurred.
wxUint32 GetLastAccess() const
It returns the number of bytes which were effectively written to/read from the sound stream.
bool QueueFilled() const
It returns whether the sound IO queue is full. When it is full, the next IO call will block until the IO queue has at least one empty entry.
void OnSoundEvent(int evt)
It is called by the wxSoundStream when a new sound event occurred.