-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% 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}{wxsoundstreamerrors} 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.
projects / wxWidgets.git / commitdiff
