contrib/docs/latex/mmedia/sndfile.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        sndfile.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{wxSoundFileStream}}\label{wxsoundfilestream}
  12
  13 Base class for file coders/decoders. This class is not constructor (it is an abstract
  14 class).
  15
  16 \wxheading{Derived from}
  17
  18 \helpref{wxSoundStream}{wxsoundstream}
  19
  20 \wxheading{Include file}
  21
  22 wx/sndfile.h
  23
  24 \wxheading{Data structures}
  25
  26 \latexignore{\rtfignore{\wxheading{Members}}}
  27
  28 \membersection{wxSoundFileStream::wxSoundFileStream}\label{wxsoundfilestreamwxsoundfilestream}
  29
  30 \func{}{wxSoundFileStream}{\param{wxInputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}}
  31
  32 It constructs a new file decoder object which will send
  33 audio data to the specified sound stream.
  34 The {\it stream} is the input stream to be decoded. The
  35 {\it io\_sound} is the destination sound stream.
  36 Once it has been constructed, you cannot change any of
  37 the specified streams nor the direction of the stream.
  38
  39 You will have access to the playback functions.
  40
  41 \func{}{wxSoundFileStream}{\param{wxOutputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}}
  42
  43 It constructs a new file coder object which will get
  44 data to be recorded from the specified sound stream.
  45 The {\it stream} is the output wxStream. The {\it io\_sound}
  46 is the source sound stream of the audio data. Once
  47 it has been constructed, you cannot change any of
  48 the specified streams nor the direction of the stream.
  49
  50 \membersection{wxSoundFileStream::\destruct{wxSoundFileStream}}\label{wxsoundfilestreamdtor}
  51 \func{}{\destruct{wxSoundFileStream}}{\void}
  52
  53 It destroys the current sound file codec.
  54
  55 \membersection{wxSoundFileStream::Play}\label{wxsoundfilestreamplay}
  56 \func{bool}{Play}{\void}
  57
  58 It starts playing the file. The playing begins, in background
  59 in nearly all cases, after the return of the function. The
  60 codec returns to a {\bf stopped} state when it reaches the
  61 end of the file.
  62 On success, it returns TRUE.
  63
  64 \membersection{wxSoundFileStream::Record}\label{wxsoundfilestreamrecord}
  65 \func{bool}{Record}{\param{wxUint32 }{time}}
  66
  67 It starts recording data from the sound stream and writing them
  68 to the output stream. You have to precise the recording length in
  69 parameter. This length is expressed in seconds. If you want to
  70 control the record length (using \helpref{Stop}{wxsoundfilestreamstop}),
  71 you can set it to wxSOUND\_INFINITE\_TIME.
  72
  73 On success, it returns TRUE.
  74
  75 \membersection{wxSoundFileStream::Stop}\label{wxsoundfilestreamstop}
  76 \func{bool}{Stop}{\void}
  77
  78 It stops either recording or playing. Whatever happens (even unexpected
  79 errors), the stream is stopped when the function returns. When you are
  80 in recording mode, the file headers are updated and flushed if possible
  81 (ie: if the output stream is seekable).
  82
  83 On success, it returns TRUE.
  84
  85 \membersection{wxSoundFileStream::Pause}\label{wxsoundfilestreampause}
  86 \func{bool}{Pause}{\void}
  87
  88 The file codec tries to pause the stream: it means that it stops audio
  89 production but keep the file pointer at the place.
  90
  91 If the file codec is already paused, it returns FALSE.
  92
  93 On success, it returns TREE.
  94
  95 \membersection{wxSoundFileStream::Resume}\label{wxsoundfilestreamresume}
  96 \func{bool}{Resume}{\void}
  97
  98 When the file codec has been paused using
  99 \helpref{Pause}{wxsoundfilestreampause}, you could be interrested in
 100 resuming it. This is the goal of this function.
 101
 102 \membersection{wxSoundFileStream::IsStopped}\label{wxsoundfilestreamisstopped}
 103 \constfunc{bool}{IsStopped}{\void}
 104
 105 It returns TRUE when the stream is stopped, in another case it returns
 106 FALSE.
 107
 108 \membersection{wxSoundFileStream::IsPaused}\label{wxsoundfilestreamispaused}
 109 \constfunc{bool}{IsPaused}{\void}
 110
 111 It returns TRUE when the stream is paused, in another case it returns
 112 FALSE.
 113
 114 \membersection{wxSoundFileStream::StartProduction}\label{wxsoundfilestreamstartproduction}
 115 \func{bool}{StartProduction}{\param{int }{evt}}
 116
 117 It is really not advised you call this function. From the wxSoundFileStream
 118 point of view it is an internal function. Internally, it is called after
 119 the file stream has been prepared to be played or to receive audio data and
 120 when it wants to start processing audio data.
 121
 122 \membersection{wxSoundFileStream::StopProduction}\label{wxsoundfilestreamstopproduction}
 123 \func{bool}{StopProduction}{\void}
 124
 125 As for \helpref{StartProduction}{wxsoundfilestreamstopproduction}, it is not
 126 advised for you to call this function. It is called by
 127 \helpref{Stop}{wxsoundfilestreamstop} when it needs to stop the audio data
 128 processing.
 129
 130 \membersection{wxSoundFileStream::GetLength}\label{wxsoundfilestreamgetlength}
 131 \func{wxUint32}{GetLength}{\void}
 132
 133 It returns the audio data length of the file stream. This length is expressed
 134 in bytes. If you need the length in seconds, you will need to use
 135 \helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and
 136 \helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.
 137
 138 \membersection{wxSoundFileStream::GetPosition}\label{wxsoundfilestreamgetposition}
 139 \func{wxUint32}{GetPosition}{\void}
 140
 141 It returns the current position in the soundfile stream. The position
 142 is expressed in bytes. If you need the length in seconds, you will need to use
 143 \helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and
 144 \helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.
 145
 146 \membersection{wxSoundFileStream::SetPosition}\label{wxsoundfilestreamsetposition}
 147 \func{wxUint32}{SetPosition}{\param{wxUint32 }{new\_position}}
 148
 149 It sets the current in the soundfile stream. The position
 150  {\it new\_position} must be expressed in bytes. You can get
 151 a length/position in bytes from a time value using
 152 \helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and
 153 \helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.
 154
 155 On success, it returns TRUE.
 156
 157 \wxheading{Warning}
 158
 159 Some wxStream may not be capable to support this function as
 160 it may not support the seekable functionnality. If this happens,
 161 it returns FALSE and leave the stream at the same position.
 162
 163 \membersection{wxSoundFileStream::Read}\label{wxsoundfilestreamread}
 164 \func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}
 165
 166 You can obtain the audio data encoded in the file using this function.
 167 But it must be considered as an internal function. Used carelessly, it
 168 may corrupt the current state of the stream.
 169 Data are returned using in the original file coding (You must use a sound
 170 format object to decode it).
 171
 172 \membersection{wxSoundFileStream::Write}\label{wxsoundfilestreamwrite}
 173 \func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}}
 174
 175 You can put encoded audio data to the file using this function.
 176 But it must be considered as an internal function. Used carelessly, it
 177 may corrupt the current state of the stream.
 178 Data must be coded with the specified file coding (You must use a sound
 179 format object to do this).
 180
 181 \membersection{wxSoundFileStream::SetSoundFormat}\label{wxsoundfilestreamsetsoundformat}
 182 \func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}}
 183
 184 \membersection{wxSoundFileStream::GetCodecName}\label{wxsoundfilestreamgetcodecname}
 185 \constfunc{wxString}{GetCodecName}{\void}
 186
 187 This function returns the Codec name. This is useful for those who
 188 want to build a player (But also in some other case).
 189
 190 \membersection{wxSoundFileStream::CanRead}\label{wxsoundfilestreamcanread}
 191 \func{bool}{CanRead}{\void}
 192
 193 You should use this function to test whether this file codec can read
 194 the stream you passed to it.
 195
 196 \membersection{wxSoundFileStream::PrepareToPlay}\label{wxsoundfilestreampreparetoplay}
 197 \func{bool}{PrepareToPlay}{\void}
 198
 199 It is called by wxSoundFileStream to prepare the specific file loader
 200 to prepare itself to play the file. Actually, this includes reading
 201 headers and setting the various parameters of the sound format.
 202 This should not be called by an external user but it should be
 203 implemented when you inherit wxSoundFileStream to build a new codec.
 204
 205 It must return when the file is identified and the parameters have
 206 been set. In all other cases, you must return FALSE.
 207
 208 \membersection{wxSoundFileStream::PrepareToRecord}\label{wxsoundfilestreampreparetorecord}
 209 \func{bool}{PrepareToRecord}{\param{wxUint32 }{time}}
 210
 211 \membersection{wxSoundFileStream::FinishRecording}\label{wxsoundfilestreamfinishrecording}
 212 \func{bool}{FinishRecording}{\void}
 213
 214 \membersection{wxSoundFileStream::RepositionStream}\label{wxsoundfilestreamrepositionstream}
 215 \func{bool}{RepositionStream}{\param{wxUint32 }{position}}
 216
 217 This is called by wxSoundFileStream::SetPosition to seek the input stream
 218 to the right position. This must be overidden by the file codec class.
 219 The position is relative to the beginning of the samples.
 220 If it is impossible (as for a piped input stream), you must return FALSE.
 221
 222 \membersection{wxSoundFileStream::FinishPreparation}\label{wxsoundfilestreamfinishpreparation}
 223 \func{void}{FinishPreparation}{\param{wxUint32 }{len}}
 224
 225 This is an internal function but it must called by the file codec class when
 226 the "playing" preparation is finished and you know the size of the stream.
 227 If it is an {\it infinite} stream, you should set this to wxSOUND\_INFINITE\_TIME.
 228
 229 \membersection{wxSoundFileStream::GetData}\label{wxsoundfilestreamgetdata}
 230 \func{wxUint32}{GetData}{\param{void* }{buffer}, \param{wxUint32 }{len}}
 231
 232 This is called by wxSoundFileStream when it needs to get new sound data to
 233 send to the device driver (or to a conversion codec). This must be eventually
 234 overidden by the file codec class. The default behaviour is simply to read from
 235 the input stream.
 236
 237 \membersection{wxSoundFileStream::PutData}\label{wxsoundfilestreamputdata}
 238 \func{wxUint32}{PutData}{\param{const void* }{buffer}, \param{wxUint32 }{len}}
 239
 240 This is called by wxSoundFileStream when it needs to put new sound data received
 241 from the device driver (or from a conversion codec). This must be eventually
 242 overidden by the file codec class. The default behaviour is simply to write to
 243 the input stream.