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 file}
  20
  21 wx/mmedia/sndbase.h
  22
  23 \wxheading{Data structures}
  24
  25 %%
  26 %% wxSoundStream errors
  27 %%
  28
  29 \wxheading{wxSoundStream errors}\label{wxsoundstreamerrors}
  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 \begin{verbatim}
  60   typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt,
  61                                   void *cdata);
  62 \end{verbatim}
  63
  64 The {\bf stream} parameter represents the current wxSoundStream.
  65
  66 The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstreamevents})
  67
  68 The {\bf cdata} parameter represents the user callback data which were specified
  69 when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}.
  70
  71 {\bf\it Note:} There is two other ways to catch sound events: you can inherit the
  72 sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}, or you can reroute the events to another sound stream using \helpref{wxSoundStream::SetEventHandler}{wxsoundstreameventhandler}
  73
  74 %%
  75 %% wxSoundStream streaming mode
  76 %%
  77
  78 \wxheading{wxSound streaming mode}
  79
  80 The wxSoundStream object can work in three different modes. These modes are specified
  81 at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction}
  82 and cannot be changed until you call
  83 \helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}.
  84
  85 The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT}
  86 events and you cannot use wxSoundStream::Write().
  87
  88 The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT}
  89 events and you cannot use wxSoundStream::Read().
  90
  91 The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex needs
  92 you make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and
  93 \helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be
  94 careful with realtime problems. Each time you call Read you must call Write.
  95
  96 %%
  97 %% wxSoundStream events
  98 %%
  99
 100 \wxheading{wxSoundStream events}
 101
 102 The sound events are generated when the sound driver (or the sound stream) completes
 103 a previous sound buffer. There are two possible sound events and two meanings.
 104
 105 The {\bf wxSOUND\_INPUT} event is generated when the sound stream has a new input
 106 buffer ready to be read. You know that you can read a buffer of the size
 107 \helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking.
 108
 109 The {\bf wxSOUND\_OUTPUT} event is generated when the sound stream has completed a
 110 previous buffer. This buffer has been sent to the sound driver and it is ready to
 111 process a new buffer. Consequently, \helpref{Write}{wxsoundstreamwrite} will not
 112 block too.
 113
 114 \latexignore{\rtfignore{\wxheading{Members}}}
 115
 116 %% Ctor && Dtor
 117
 118 \membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream}
 119
 120 \func{}{wxSoundStream}{\void}
 121
 122 Default constructor.
 123
 124 \membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor}
 125
 126 \func{}{\destruct{wxSoundStream}}{\void}
 127
 128 Destructor. The destructor stops automatically all started production and destroys
 129 any temporary buffer.
 130
 131 %%
 132 %% Read
 133 %%
 134
 135 \membersection{wxSoundStream::Read}\label{wxsoundstreamread}
 136
 137 \func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}
 138
 139 Reads \it{len} bytes from the sound stream. This call may block the user so
 140 use it carefully when you need to intensively refresh the GUI. You may be
 141 interested by sound events: see
 142 \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
 143 It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
 144 sound event system.
 145
 146 \wxheading{Note on \it{len}}
 147
 148 \it{len} is expressed in bytes. If you need to do conversions between bytes
 149 and seconds use wxSoundFormat.
 150 See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
 151
 152 \wxheading{Note on data}
 153
 154 Data in \it{buffer} are coded using the sound format attached to this sound
 155 stream. The format is specified with
 156 \helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}
 157
 158 %%
 159 %% Write
 160 %%
 161
 162 \membersection{wxSoundStream::Write}\label{wxsoundstreamwrite}
 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{Note on \it{len}}
 173
 174 \it{len} 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 \wxheading{Note on data}
 179
 180 Data in \it{buffer} are coded using the sound format attached to this sound
 181 stream. The format is specified with
 182 \helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}
 183
 184 %%
 185 %% GetBestSize
 186 %%
 187
 188 \membersection{wxSoundStream::GetBestSize}\label{wxsoundstreamgetbestsize}
 189
 190 \constfunc{wxUint32}{GetBestSize}{\void}
 191
 192 This function returns the best size for IO calls. The best size provides you
 193 a good alignment for data to be written (or read) to (or from) the sound stream.
 194 So, when, for example, a sound event is sent, you are sure the sound stream
 195 will not block for this buffer size.
 196
 197 %%
 198 %% wxSoundStream:SetSoundFormat
 199 %%
 200
 201 \membersection{wxSoundStream::SetSoundFormat}\label{wxsoundstreamsetsoundformat}
 202 \func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}}
 203
 204 SetSoundFormat is one of the key function of the wxSoundStream object. It specifies
 205 the sound format the user needs. SetSoundFormat tries to apply the format to the
 206 current sound stream (it can be a sound file or a sound driver).
 207 Then, either it manages to apply it and it returns {\bf TRUE}, or it could not and
 208 it returns {\bf FALSE}. In this case, you must check the error with
 209 \helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
 210 \helpref{wxSoundStream errors section}{wxsoundstreamerrors} for more details.
 211
 212 \wxheading{Remark}
 213
 214 The {\bf format} object can be destroyed after the call. The object does not need it.
 215
 216 %%
 217 %% GetSoundFormat
 218 %%
 219 \membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat}
 220 \constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void}
 221
 222 It returns a reference to the current sound format of the stream represented by a
 223 wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except
 224 the stream itself.
 225
 226 %%
 227 %% SetCallback
 228 %%
 229 \membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister}
 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
 253 \membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler}
 254
 255 \func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}}
 256
 257 Sets the event handler: if it is non-null, all events are routed to it.
 258
 259
 260 \membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror}
 261 \constfunc{wxSoundError}{GetError}{\void}
 262
 263
 264 \membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
 265 \constfunc{wxUint32}{GetLastAccess}{\void}
 266
 267
 268 \membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled}
 269 \constfunc{bool}{QueueFilled}{\void}
 270
 271 This is only useful for device (I think).
 272
 273
 274 \membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent}
 275 \func{void}{OnSoundEvent}{\param{int }{evt}}
 276
 277 Handles event