1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: sndbase.tex 3%% Purpose: wxMMedia docs 4%% Author: Guilhem Lavaux <lavaux@easynet.fr> 5%% Modified by: 6%% Created: 2000 7%% RCS-ID: $Id: sndbase.tex 34436 2005-05-31 09:20:43Z JS $ 8%% Copyright: (c) wxWindows team 9%% Licence: wxWindows licence 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11\section{\class{wxSoundStream}}\label{wxsoundstream} 12 13Base class for sound streams 14 15\wxheading{Derived from} 16 17No base class 18 19\wxheading{Include files} 20 21<wx/mmedia/sndbase.h> 22 23\wxheading{Data structures} 24 25%% 26%% wxSoundStream errors 27%% 28 29\wxheading{wxSoundStream errors} 30 31\twocolwidtha{7cm} 32\begin{twocollist}\itemsep=0pt 33\twocolitem{{\bf wxSOUND\_NOERR}}{No error occurred} 34\twocolitem{{\bf wxSOUND\_IOERR}}{An input/output error occurred, it may concern 35either a driver or a file} 36\twocolitem{{\bf wxSOUND\_INVFRMT}}{The sound format passed to the function is 37invalid. Generally, it means that you passed out of range values to the codec 38stream or you don't pass the right sound format object to the right sound codec 39stream.} 40\twocolitem{{\bf wxSOUND\_INVDEV}}{Invalid device. Generally, it means that the 41sound stream didn't manage to open the device driver due to an invalid parameter 42or to the fact that sound is not supported on this computer.} 43\twocolitem{{\bf wxSOUND\_NOEXACT}}{No exact matching sound codec has been found for 44this sound format. It means that the sound driver didn't manage to setup the sound 45card with the specified values.} 46\twocolitem{{\bf wxSOUND\_NOCODEC}}{No matching codec has been found. Generally, it 47may happen when you call wxSoundRouterStream::SetSoundFormat().} 48\twocolitem{{\bf wxSOUND\_MEMERR}}{Not enough memory.} 49\end{twocollist} 50 51%% 52%% C callback 53%% 54 55\wxheading{C callback for wxSound event} 56 57When a sound event is generated, it may either call the internal sound event 58processor (which can be inherited) or call a C function. Its definition is: 59 60\begin{verbatim} 61 typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt, 62 void *cdata); 63\end{verbatim} 64 65The {\bf stream} parameter represents the current wxSoundStream. 66 67The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}). 68 69The {\bf cdata} parameter represents the user callback data which were specified 70when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}. 71 72{\it Note:} There are two other ways to catch sound events: you can inherit the 73sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}, or you can reroute the events to another sound stream using \helpref{wxSoundStream::SetEventHandler}{wxsoundstreamseteventhandler}. 74 75%% 76%% wxSoundStream streaming mode 77%% 78 79\wxheading{wxSound streaming mode} 80 81The wxSoundStream object can work in three different modes. These modes are specified 82at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction} 83and cannot be changed until you call 84\helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}. 85 86The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT} 87events and you cannot use wxSoundStream::Write(). 88 89The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT} 90events and you cannot use wxSoundStream::Read(). 91 92The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires 93you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and 94\helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be 95careful with realtime problems. Each time you call Read you must call Write. 96 97%% 98%% wxSoundStream events 99%% 100 101\wxheading{wxSoundStream events} 102 103The sound events are generated when the sound driver (or the sound stream) completes 104a previous sound buffer. There are two possible sound events and two meanings. 105 106The {\bf wxSOUND\_INPUT} event is generated when the sound stream has a new input 107buffer ready to be read. You know that you can read a buffer of the size 108\helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking. 109 110The {\bf wxSOUND\_OUTPUT} event is generated when the sound stream has completed a 111previous buffer. This buffer has been sent to the sound driver and it is ready to 112process a new buffer. Consequently, \helpref{Write}{wxsoundstreamwrite} will not 113block too. 114 115\latexignore{\rtfignore{\wxheading{Members}}} 116 117%% Ctor && Dtor 118 119\membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream} 120 121\func{}{wxSoundStream}{\void} 122 123Default constructor. 124 125\membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor} 126 127\func{}{\destruct{wxSoundStream}}{\void} 128 129Destructor. The destructor stops automatically all started production and destroys 130any temporary buffer. 131 132%% 133%% Read 134%% 135 136\membersection{wxSoundStream::Read}\label{wxsoundstreamread} 137 138\func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}} 139 140Reads {\it len} bytes from the sound stream. This call may block the user so 141use it carefully when you need to intensively refresh the GUI. You may be 142interested by sound events: see \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}. 143 144It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the 145sound event system. 146 147\wxheading{Parameters} 148 149\docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes 150and seconds use wxSoundFormat. 151See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.} 152 153\docparam{data}{Data in \it{buffer} are coded using the sound format attached to this sound 154stream. The format is specified with 155\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.} 156 157%% 158%% Write 159%% 160 161\membersection{wxSoundStream::Write}\label{wxsoundstreamwrite} 162 163\func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}} 164 165Writes \it{len} bytes to the sound stream. This call may block the user so 166use it carefully. You may be interested by sound events: see 167\helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}. 168 169It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the 170sound event system. 171 172\wxheading{Parameters} 173 174\docparam{len}{This is expressed in bytes. If you need to do conversions between bytes 175and seconds use wxSoundFormat. 176See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.} 177 178\docparam{buffer}{Data in \it{buffer} are coded using the sound format attached to this sound 179stream. The format is specified with 180\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.} 181 182%% 183%% GetBestSize 184%% 185 186\membersection{wxSoundStream::GetBestSize}\label{wxsoundstreamgetbestsize} 187 188\constfunc{wxUint32}{GetBestSize}{\void} 189 190This function returns the best size for IO calls. The best size provides you 191a good alignment for data to be written (or read) to (or from) the sound stream. 192So, when, for example, a sound event is sent, you are sure the sound stream 193will not block for this buffer size. 194 195%% 196%% wxSoundStream:SetSoundFormat 197%% 198 199\membersection{wxSoundStream::SetSoundFormat}\label{wxsoundstreamsetsoundformat} 200 201\func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}} 202 203SetSoundFormat is one of the key function of the wxSoundStream object. 204It specifies the sound format the user needs. SetSoundFormat tries to 205apply the format to the current sound stream (it can be a sound file or a 206sound driver). Then, either it manages to apply it and it returns {\bf TRUE}, 207or it could not and it returns {\bf FALSE}. In this case, you must check 208the error with 209\helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See 210\helpref{wxSoundStream errors section}{wxsoundstream} for more details. 211 212\wxheading{Note} 213 214The {\bf format} object can be destroyed after the call. The object does not need it. 215 216\wxheading{Note} 217 218If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best 219approaching format and setups it. You can check the format which it applied 220with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}. 221 222%% 223%% GetSoundFormat 224%% 225\membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat} 226\constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void} 227 228It returns a reference to the current sound format of the stream represented by a 229wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except 230the stream itself. 231 232%% 233%% SetCallback 234%% 235\membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister} 236 237\func{void}{Register}{\param{int }{evt}, \param{wxSoundCallback }{cbk}, \param{void* }{cdata}} 238 239It installs a C callback for wxSoundStream events. The C callbacks are still 240useful to avoid hard inheritance. You can install only one callback per event. 241Each callback has its callback data. 242 243%% 244%% StartProduction 245%% 246\membersection{wxSoundStream::StartProduction}\label{wxsoundstreamstartproduction} 247 248\func{bool}{StartProduction}{\param{int }{evt}} 249 250StartProduction starts the sound streaming. {\it evt} may be one of 251{\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf wxSOUND\_DUPLEX}. 252You cannot specify several flags at the same time. Starting the production 253may automaticaly in position of buffer underrun (only in the case you activated 254recording). Actually this may happen the sound IO queue is too short. 255It is also advised that you fill quickly enough the sound IO queue when the 256driver requests it (through a wxSoundEvent). 257 258\membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction} 259 260\func{bool}{StopProduction}{\void} 261 262I stops the async notifier and the sound streaming straightly. 263 264\membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler} 265 266\func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}} 267 268Sets the event handler: if it is non-null, all events are routed to it. 269 270\membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror} 271 272\constfunc{wxSoundError}{GetError}{\void} 273 274It returns the last error which occurred. 275 276\membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess} 277 278\constfunc{wxUint32}{GetLastAccess}{\void} 279 280It returns the number of bytes which were effectively written to/read from the sound stream. 281 282\membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled} 283 284\constfunc{bool}{QueueFilled}{\void} 285 286It returns whether the sound IO queue is full. When it is full, the next IO call will block 287until the IO queue has at least one empty entry. 288 289\membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent} 290 291\func{void}{OnSoundEvent}{\param{int }{evt}} 292 293It is called by the wxSoundStream when a new sound event occurred. 294 295