Contents Up Previous Next

wxSoundStream

Base class for sound streams

Derived from

No base class

Include files

<wx/mmedia/sndbase.h>

Data structures

wxSoundStream errors

wxSOUND_NOERR No error occured
wxSOUND_IOERR An input/output error occured, 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::wxSoundStream

wxSoundStream()

Default constructor.


wxSoundStream::~wxSoundStream

~wxSoundStream()

Destructor. The destructor stops automatically all started production and destroys any temporary buffer.


wxSoundStream::Read

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

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


wxSoundStream::GetBestSize

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.


wxSoundStream::SetSoundFormat

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.


wxSoundStream::GetSoundFormat

wxSoundFormatBase& GetSoundFormat() const

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.


wxSoundStream::SetCallback

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.


wxSoundStream::StartProduction

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).


wxSoundStream::StopProduction

bool StopProduction()

I stops the async notifier and the sound streaming straightly.


wxSoundStream::SetEventHandler

void SetEventHandler(wxSoundStream* handler)

Sets the event handler: if it is non-null, all events are routed to it.


wxSoundStream::GetError

wxSoundError GetError() const

It returns the last error which occured.


wxSoundStream::GetLastAccess

wxUint32 GetLastAccess() const

It returns the number of bytes which were effectively written to/read from the sound stream.


wxSoundStream::QueueFilled

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.


wxSoundStream::OnSoundEvent

void OnSoundEvent(int evt)

It is called by the wxSoundStream when a new sound event occured.