contrib/docs/latex/mmedia/sndbase.tex

   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$
   8 %% Copyright:   (c) wxWindows team
   9 %% Licence:     wxWindows licence
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11 \section{\class{wxSoundStream}}\label{wxsoundstream}
  12
  13 Base class for sound streams
  14
  15 \wxheading{Derived from}
  16
  17 No 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
  35 either a driver or a file}
  36 \twocolitem{{\bf wxSOUND\_INVFRMT}}{The sound format passed to the function is
  37 invalid. Generally, it means that you passed out of range values to the codec
  38 stream or you don't pass the right sound format object to the right sound codec
  39 stream.}
  40 \twocolitem{{\bf wxSOUND\_INVDEV}}{Invalid device. Generally, it means that the
  41 sound stream didn't manage to open the device driver due to an invalid parameter
  42 or 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
  44 this sound format. It means that the sound driver didn't manage to setup the sound
  45 card with the specified values.}
  46 \twocolitem{{\bf wxSOUND\_NOCODEC}}{No matching codec has been found. Generally, it
  47 may 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
  57 When a sound event is generated, it may either call the internal sound event
  58 processor (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
  65 The {\bf stream} parameter represents the current wxSoundStream.
  66
  67 The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}).
  68
  69 The {\bf cdata} parameter represents the user callback data which were specified
  70 when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}.
  71
  72 {\it Note:} There are two other ways to catch sound events: you can inherit the
  73 sound 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
  81 The wxSoundStream object can work in three different modes. These modes are specified
  82 at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction}
  83 and cannot be changed until you call
  84 \helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}.
  85
  86 The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT}
  87 events and you cannot use wxSoundStream::Write().
  88
  89 The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT}
  90 events and you cannot use wxSoundStream::Read().
  91
  92 The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires
  93 you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and
  94 \helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be
  95 careful with realtime problems. Each time you call Read you must call Write.
  96
  97 %%
  98 %% wxSoundStream events
  99 %%
 100
 101 \wxheading{wxSoundStream events}
 102
 103 The sound events are generated when the sound driver (or the sound stream) completes
 104 a previous sound buffer. There are two possible sound events and two meanings.
 105
 106 The {\bf wxSOUND\_INPUT} event is generated when the sound stream has a new input
 107 buffer ready to be read. You know that you can read a buffer of the size
 108 \helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking.
 109
 110 The {\bf wxSOUND\_OUTPUT} event is generated when the sound stream has completed a
 111 previous buffer. This buffer has been sent to the sound driver and it is ready to
 112 process a new buffer. Consequently, \helpref{Write}{wxsoundstreamwrite} will not
 113 block too.
 114
 115 \latexignore{\rtfignore{\wxheading{Members}}}
 116
 117 %% Ctor && Dtor
 118
 119 \membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream}
 120
 121 \func{}{wxSoundStream}{\void}
 122
 123 Default constructor.
 124
 125 \membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor}
 126
 127 \func{}{\destruct{wxSoundStream}}{\void}
 128
 129 Destructor. The destructor stops automatically all started production and destroys
 130 any 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
 140 Reads {\it len} bytes from the sound stream. This call may block the user so
 141 use it carefully when you need to intensively refresh the GUI. You may be
 142 interested by sound events: see \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
 143
 144 It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
 145 sound event system.
 146
 147 \wxheading{Parameters}
 148
 149 \docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes
 150 and seconds use wxSoundFormat.
 151 See \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
 154 stream. 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
 165 Writes \it{len} bytes to the sound stream. This call may block the user so
 166 use it carefully. You may be interested by sound events: see
 167 \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
 168
 169 It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
 170 sound event system.
 171
 172 \wxheading{Parameters}
 173
 174 \docparam{len}{This is expressed in bytes. If you need to do conversions between bytes
 175 and seconds use wxSoundFormat.
 176 See \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
 179 stream. 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
 190 This function returns the best size for IO calls. The best size provides you
 191 a good alignment for data to be written (or read) to (or from) the sound stream.
 192 So, when, for example, a sound event is sent, you are sure the sound stream
 193 will 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
 203 SetSoundFormat is one of the key function of the wxSoundStream object.
 204 It specifies the sound format the user needs. SetSoundFormat tries to
 205 apply the format to the current sound stream (it can be a sound file or a
 206 sound driver). Then, either it manages to apply it and it returns {\bf TRUE},
 207 or it could not and it returns {\bf FALSE}. In this case, you must check
 208 the error with
 209 \helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
 210 \helpref{wxSoundStream errors section}{wxsoundstream} for more details.
 211
 212 \wxheading{Note}
 213
 214 The {\bf format} object can be destroyed after the call. The object does not need it.
 215
 216 \wxheading{Note}
 217
 218 If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best
 219 approaching format and setups it. You can check the format which it applied
 220 with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
 221
 222 %%
 223 %% GetSoundFormat
 224 %%
 225 \membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat}
 226 \constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void}
 227
 228 It returns a reference to the current sound format of the stream represented by a
 229 wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except
 230 the 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
 239 It installs a C callback for wxSoundStream events. The C callbacks are still
 240 useful to avoid hard inheritance. You can install only one callback per event.
 241 Each 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
 250 StartProduction starts the sound streaming. {\it evt} may be one of
 251 {\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf wxSOUND\_DUPLEX}.
 252 You cannot specify several flags at the same time. Starting the production
 253 may automaticaly in position of buffer underrun (only in the case you activated
 254 recording). Actually this may happen the sound IO queue is too short.
 255 It is also advised that you fill quickly enough the sound IO queue when the
 256 driver requests it (through a wxSoundEvent).
 257
 258 \membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction}
 259
 260 \func{bool}{StopProduction}{\void}
 261
 262 I 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
 268 Sets 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
 274 It returns the last error which occurred.
 275
 276 \membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
 277
 278 \constfunc{wxUint32}{GetLastAccess}{\void}
 279
 280 It 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
 286 It returns whether the sound IO queue is full. When it is full, the next IO call will block
 287 until 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
 293 It is called by the wxSoundStream when a new sound event occurred.
 294