%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Name: sndbase.tex %% Purpose: wxMMedia docs %% Author: Guilhem Lavaux %% Modified by: %% Created: 2000 %% RCS-ID: $Id: sndbase.tex 34436 2005-05-31 09:20:43Z JS $ %% 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} \wxheading{Data structures} %% %% wxSoundStream errors %% \wxheading{wxSoundStream errors} \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt \twocolitem{{\bf wxSOUND\_NOERR}}{No error occurred} \twocolitem{{\bf wxSOUND\_IOERR}}{An input/output error occurred, 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 occurred. \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 occurred.