5d525ad911
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6693 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
295 lines
11 KiB
TeX
295 lines
11 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: sndbase.tex
|
|
%% Purpose: wxMMedia docs
|
|
%% Author: Guilhem Lavaux <lavaux@easynet.fr>
|
|
%% Modified by:
|
|
%% Created: 2000
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) wxWindows team
|
|
%% Licence: wxWindows licence
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{\class{wxSoundStream}}\label{wxsoundstream}
|
|
|
|
Base class for sound streams
|
|
|
|
\wxheading{Derived from}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/mmedia/sndbase.h>
|
|
|
|
\wxheading{Data structures}
|
|
|
|
%%
|
|
%% wxSoundStream errors
|
|
%%
|
|
|
|
\wxheading{wxSoundStream errors}
|
|
|
|
\twocolwidtha{7cm}
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitem{{\bf wxSOUND\_NOERR}}{No error occured}
|
|
\twocolitem{{\bf wxSOUND\_IOERR}}{An input/output error occured, it may concern
|
|
either a driver or a file}
|
|
\twocolitem{{\bf 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.}
|
|
\twocolitem{{\bf 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.}
|
|
\twocolitem{{\bf 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.}
|
|
\twocolitem{{\bf wxSOUND\_NOCODEC}}{No matching codec has been found. Generally, it
|
|
may happen when you call wxSoundRouterStream::SetSoundFormat().}
|
|
\twocolitem{{\bf wxSOUND\_MEMERR}}{Not enough memory.}
|
|
\end{twocollist}
|
|
|
|
%%
|
|
%% C callback
|
|
%%
|
|
|
|
\wxheading{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:
|
|
|
|
\begin{verbatim}
|
|
typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt,
|
|
void *cdata);
|
|
\end{verbatim}
|
|
|
|
The {\bf stream} parameter represents the current wxSoundStream.
|
|
|
|
The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}).
|
|
|
|
The {\bf cdata} parameter represents the user callback data which were specified
|
|
when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}.
|
|
|
|
{\it Note:} There are two other ways to catch sound events: you can inherit the
|
|
sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}, or you can reroute the events to another sound stream using \helpref{wxSoundStream::SetEventHandler}{wxsoundstreamseteventhandler}.
|
|
|
|
%%
|
|
%% wxSoundStream streaming mode
|
|
%%
|
|
|
|
\wxheading{wxSound streaming mode}
|
|
|
|
The wxSoundStream object can work in three different modes. These modes are specified
|
|
at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction}
|
|
and cannot be changed until you call
|
|
\helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}.
|
|
|
|
The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT}
|
|
events and you cannot use wxSoundStream::Write().
|
|
|
|
The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT}
|
|
events and you cannot use wxSoundStream::Read().
|
|
|
|
The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires
|
|
you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and
|
|
\helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be
|
|
careful with realtime problems. Each time you call Read you must call Write.
|
|
|
|
%%
|
|
%% wxSoundStream events
|
|
%%
|
|
|
|
\wxheading{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 {\bf 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
|
|
\helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking.
|
|
|
|
The {\bf 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, \helpref{Write}{wxsoundstreamwrite} will not
|
|
block too.
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
%% Ctor && Dtor
|
|
|
|
\membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream}
|
|
|
|
\func{}{wxSoundStream}{\void}
|
|
|
|
Default constructor.
|
|
|
|
\membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor}
|
|
|
|
\func{}{\destruct{wxSoundStream}}{\void}
|
|
|
|
Destructor. The destructor stops automatically all started production and destroys
|
|
any temporary buffer.
|
|
|
|
%%
|
|
%% Read
|
|
%%
|
|
|
|
\membersection{wxSoundStream::Read}\label{wxsoundstreamread}
|
|
|
|
\func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}
|
|
|
|
Reads {\it 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 \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
|
|
|
|
It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
|
|
sound event system.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes
|
|
and seconds use wxSoundFormat.
|
|
See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.}
|
|
|
|
\docparam{data}{Data in \it{buffer} are coded using the sound format attached to this sound
|
|
stream. The format is specified with
|
|
\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.}
|
|
|
|
%%
|
|
%% Write
|
|
%%
|
|
|
|
\membersection{wxSoundStream::Write}\label{wxsoundstreamwrite}
|
|
|
|
\func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}}
|
|
|
|
Writes \it{len} bytes to the sound stream. This call may block the user so
|
|
use it carefully. You may be interested by sound events: see
|
|
\helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
|
|
|
|
It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
|
|
sound event system.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{len}{This is expressed in bytes. If you need to do conversions between bytes
|
|
and seconds use wxSoundFormat.
|
|
See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.}
|
|
|
|
\docparam{buffer}{Data in \it{buffer} are coded using the sound format attached to this sound
|
|
stream. The format is specified with
|
|
\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.}
|
|
|
|
%%
|
|
%% GetBestSize
|
|
%%
|
|
|
|
\membersection{wxSoundStream::GetBestSize}\label{wxsoundstreamgetbestsize}
|
|
|
|
\constfunc{wxUint32}{GetBestSize}{\void}
|
|
|
|
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
|
|
%%
|
|
|
|
\membersection{wxSoundStream::SetSoundFormat}\label{wxsoundstreamsetsoundformat}
|
|
|
|
\func{bool}{SetSoundFormat}{\param{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 {\bf TRUE},
|
|
or it could not and it returns {\bf FALSE}. In this case, you must check
|
|
the error with
|
|
\helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
|
|
\helpref{wxSoundStream errors section}{wxsoundstream} for more details.
|
|
|
|
\wxheading{Note}
|
|
|
|
The {\bf format} object can be destroyed after the call. The object does not need it.
|
|
|
|
\wxheading{Note}
|
|
|
|
If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best
|
|
approaching format and setups it. You can check the format which it applied
|
|
with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
|
|
|
|
%%
|
|
%% GetSoundFormat
|
|
%%
|
|
\membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat}
|
|
\constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void}
|
|
|
|
It returns a reference to the current sound format of the stream represented by a
|
|
wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except
|
|
the stream itself.
|
|
|
|
%%
|
|
%% SetCallback
|
|
%%
|
|
\membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister}
|
|
|
|
\func{void}{Register}{\param{int }{evt}, \param{wxSoundCallback }{cbk}, \param{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.
|
|
|
|
%%
|
|
%% StartProduction
|
|
%%
|
|
\membersection{wxSoundStream::StartProduction}\label{wxsoundstreamstartproduction}
|
|
|
|
\func{bool}{StartProduction}{\param{int }{evt}}
|
|
|
|
StartProduction starts the sound streaming. {\it evt} may be one of
|
|
{\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf 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).
|
|
|
|
\membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction}
|
|
|
|
\func{bool}{StopProduction}{\void}
|
|
|
|
I stops the async notifier and the sound streaming straightly.
|
|
|
|
\membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler}
|
|
|
|
\func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}}
|
|
|
|
Sets the event handler: if it is non-null, all events are routed to it.
|
|
|
|
\membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror}
|
|
|
|
\constfunc{wxSoundError}{GetError}{\void}
|
|
|
|
It returns the last error which occured.
|
|
|
|
\membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
|
|
|
|
\constfunc{wxUint32}{GetLastAccess}{\void}
|
|
|
|
It returns the number of bytes which were effectively written to/read from the sound stream.
|
|
|
|
\membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled}
|
|
|
|
\constfunc{bool}{QueueFilled}{\void}
|
|
|
|
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.
|
|
|
|
\membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent}
|
|
|
|
\func{void}{OnSoundEvent}{\param{int }{evt}}
|
|
|
|
It is called by the wxSoundStream when a new sound event occured.
|
|
|