docs/latex/wx/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 occured}
  34 \twocolitem{{\bf wxSOUND\_IOERR}}{An input/output error occured, 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. It specifies
 204 the sound format the user needs. SetSoundFormat tries to apply the format to the
 205 current sound stream (it can be a sound file or a sound driver).
 206 Then, either it manages to apply it and it returns {\bf TRUE}, or it could not and
 207 it returns {\bf FALSE}. In this case, you must check the error with
 208 \helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
 209 \helpref{wxSoundStream errors section}{wxsoundstream} for more details.
 210
 211 \wxheading{Remark}
 212
 213 The {\bf format} object can be destroyed after the call. The object does not need it.
 214
 215 %%
 216 %% GetSoundFormat
 217 %%
 218 \membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat}
 219 \constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void}
 220
 221 It returns a reference to the current sound format of the stream represented by a
 222 wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except
 223 the stream itself.
 224
 225 %%
 226 %% SetCallback
 227 %%
 228 \membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister}
 229
 230 \func{void}{Register}{\param{int }{evt}, \param{wxSoundCallback }{cbk}, \param{void* }{cdata}}
 231
 232 It installs a C callback for wxSoundStream events. The C callbacks are still useful
 233 to avoid hard inheritance. You can install only one callback per event. Each callback
 234 has its callback data.
 235
 236 %%
 237 %% StartProduction
 238 %%
 239 \membersection{wxSoundStream::StartProduction}\label{wxsoundstreamstartproduction}
 240
 241 \func{bool}{StartProduction}{\param{int }{evt}}
 242
 243 Starts the async notifier. After this call, the stream begins either
 244 recording or playing or the two at the same time.
 245
 246 \membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction}
 247
 248 \func{bool}{StopProduction}{\void}
 249
 250 Stops the async notifier.
 251
 252 \membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler}
 253
 254 \func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}}
 255
 256 Sets the event handler: if it is non-null, all events are routed to it.
 257
 258 \membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror}
 259
 260 \constfunc{wxSoundError}{GetError}{\void}
 261
 262 \membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
 263
 264 \constfunc{wxUint32}{GetLastAccess}{\void}
 265
 266 \membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled}
 267
 268 \constfunc{bool}{QueueFilled}{\void}
 269
 270 This is only useful for device (I think).
 271
 272 \membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent}
 273
 274 \func{void}{OnSoundEvent}{\param{int }{evt}}
 275
 276 Handles event.
 277