%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        sndfile.tex
%% Purpose:     wxMMedia docs
%% Author:      Guilhem Lavaux <lavaux@easynet.fr>
%% Modified by:
%% Created:     2000
%% RCS-ID:      $Id$
%% Copyright:   (c) wxWindows team
%% Licence:     wxWindows licence
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxSoundFileStream}}\label{wxsoundfilestream}

Base class for file coders/decoders. This class is not constructor (it is an abstract
class).

\wxheading{Derived from}

\helpref{wxSoundStream}{wxsoundstream}

\wxheading{Include file}

wx/sndfile.h

\wxheading{Data structures}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxSoundFileStream::wxSoundFileStream}\label{wxsoundfilestreamwxsoundfilestream}

\func{}{wxSoundFileStream}{\param{wxInputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}}

It constructs a new file decoder object which will send 
audio data to the specified sound stream. 
The {\it stream} is the input stream to be decoded. The
{\it io_sound} is the destination sound stream.
Once it has been constructed, you cannot change any of
the specified streams nor the direction of the stream.

You will have access to the playback functions.

\func{}{wxSoundFileStream}{\param{wxOutputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}}

It constructs a new file coder object which will get
data to be recorded from the specified sound stream.
The {\it stream} is the output wxStream. The {\it io_sound}
is the source sound stream of the audio data. Once
it has been constructed, you cannot change any of
the specified streams nor the direction of the stream.

\membersection{wxSoundFileStream::\destruct{wxSoundFileStream}}\label{wxsoundfilestreamdtor}
\func{}{\destruct{wxSoundFileStream}}{\void}

It destroys the current sound file codec.

\membersection{wxSoundFileStream::Play}\label{wxsoundfilestreamplay}
\func{bool}{Play}{\void}

It starts playing the file. The playing begins, in background
in nearly all cases, after the return of the function. The
codec returns to a {\bf stopped} state when it reaches the
end of the file.
On success, it returns TRUE.

\membersection{wxSoundFileStream::Record}\label{wxsoundfilestreamrecord}
\func{bool}{Record}{\param{wxUint32 }{time}}

It starts recording data from the sound stream and writing them
to the output stream. You have to precise the recording length in
parameter. This length is expressed in seconds. If you want to
control the record length (using \helpref{Stop}{wxsoundfilestreamstop}),
you can set it to wxSOUND_INFINITE_TIME.

On success, it returns TRUE.

\membersection{wxSoundFileStream::Stop}\label{wxsoundfilestreamstop}
\func{bool}{Stop}{\void}

It stops either recording or playing. Whatever happens (even unexpected
errors), the stream is stopped when the function returns. When you are
in recording mode, the file headers are updated and flushed if possible
(ie: if the output stream is seekable).

On success, it returns TRUE.

\membersection{wxSoundFileStream::Pause}\label{wxsoundfilestreampause}
\func{bool}{Pause}{\void}

The file codec tries to pause the stream: it means that it stops audio
production but keep the file pointer at the place.

If the file codec is already paused, it returns FALSE.

On success, it returns TREE.

\membersection{wxSoundFileStream::Resume}\label{wxsoundfilestreamresume}
\func{bool}{Resume}{\void}

When the file codec has been paused using
\helpref{Pause}{wxsoundfilestreampause}, you could be interrested in
resuming it. This is the goal of this function.

\membersection{wxSoundFileStream::IsStopped}\label{wxsoundfilestreamisstopped}
\constfunc{bool}{IsStopped}{\void}

\membersection{wxSoundFileStream::IsPaused}\label{wxsoundfilestreamispaused}
\constfunc{bool}{IsPaused}{\void}

\membersection{wxSoundFileStream::StartProduction}\label{wxsoundfilestreamstartproduction}
\func{bool}{StartProduction}{\param{int }{evt}}

A user should not call these two functions.
Several things must be done before calling them.
Users should use Play(), ... 


\membersection{wxSoundFileStream::StopProduction}\label{wxsoundfilestreamstopproduction}

\func{bool}{StopProduction}{\void}


\membersection{wxSoundFileStream::GetLength}\label{wxsoundfilestreamgetlength}

\func{wxUint32}{GetLength}{\void}

These three functions deals with the length, the position in the sound file.
All the values are expressed in bytes. If you need the values expressed
in terms of time, you have to use GetSoundFormat().GetTimeFromBytes(...)

\membersection{wxSoundFileStream::GetPosition}\label{wxsoundfilestreamgetposition}

\func{wxUint32}{GetPosition}{\void}


\membersection{wxSoundFileStream::SetPosition}\label{wxsoundfilestreamsetposition}

\func{wxUint32}{SetPosition}{\param{wxUint32 }{new\_position}}


\membersection{wxSoundFileStream::Read}\label{wxsoundfilestreamread}

\func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}

These two functions use the sound format specified by GetSoundFormat().
All samples must be encoded in that format. 


\membersection{wxSoundFileStream::Write}\label{wxsoundfilestreamwrite}

\func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}}


\membersection{wxSoundFileStream::SetSoundFormat}\label{wxsoundfilestreamsetsoundformat}

\func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}}

This function set the sound format of the file. !! It must be used only
when you are in output mode (concerning the file) !! If you are in
input mode (concerning the file) you can't use this function to modify
the format of the samples returned by Read() !
For this action, you must use wxSoundRouterStream applied to wxSoundFileStream. 


\membersection{wxSoundFileStream::GetCodecName}\label{wxsoundfilestreamgetcodecname}

\constfunc{wxString}{GetCodecName}{\void}

This function returns the Codec name. This is useful for those who want to build
a player (But also in some other case).


\membersection{wxSoundFileStream::CanRead}\label{wxsoundfilestreamcanread}

\func{bool}{CanRead}{\void}

You should use this function to test whether this file codec can read
the stream you passed to it.


\membersection{wxSoundFileStream::PrepareToPlay}\label{wxsoundfilestreampreparetoplay}

\func{bool}{PrepareToPlay}{\void}


\membersection{wxSoundFileStream::PrepareToRecord}\label{wxsoundfilestreampreparetorecord}

\func{bool}{PrepareToRecord}{\param{wxUint32 }{time}}


\membersection{wxSoundFileStream::FinishRecording}\label{wxsoundfilestreamfinishrecording}

\func{bool}{FinishRecording}{\void}


\membersection{wxSoundFileStream::RepositionStream}\label{wxsoundfilestreamrepositionstream}

\func{bool}{RepositionStream}{\param{wxUint32 }{position}}


\membersection{wxSoundFileStream::FinishPreparation}\label{wxsoundfilestreamfinishpreparation}

\func{void}{FinishPreparation}{\param{wxUint32 }{len}}


\membersection{wxSoundFileStream::GetData}\label{wxsoundfilestreamgetdata}

\func{wxUint32}{GetData}{\param{void* }{buffer}, \param{wxUint32 }{len}}


\membersection{wxSoundFileStream::PutData}\label{wxsoundfilestreamputdata}

\func{wxUint32}{PutData}{\param{const void* }{buffer}, \param{wxUint32 }{len}}


\membersection{wxSoundFileStream::OnSoundEvent}\label{wxsoundfilestreamonsoundevent}

\func{void}{OnSoundEvent}{\param{int }{evt}}

