Tools

[wxWidgets.git] / contrib / docs / latex / mmedia / sndfile.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% 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}

It returns TRUE when the stream is stopped, in another case it returns
FALSE.

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

It returns TRUE when the stream is paused, in another case it returns
FALSE.

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

It is really not advised you call this function. From the wxSoundFileStream
point of view it is an internal function. Internally, it is called after
the file stream has been prepared to be played or to receive audio data and 
when it wants to start processing audio data.

\membersection{wxSoundFileStream::StopProduction}\label{wxsoundfilestreamstopproduction}
\func{bool}{StopProduction}{\void}

As for \helpref{StartProduction}{wxsoundfilestreamstopproduction}, it is not
advised for you to call this function. It is called by
\helpref{Stop}{wxsoundfilestreamstop} when it needs to stop the audio data
processing.

\membersection{wxSoundFileStream::GetLength}\label{wxsoundfilestreamgetlength}
\func{wxUint32}{GetLength}{\void}

It returns the audio data length of the file stream. This length is expressed
in bytes. If you need the length in seconds, you will need to use
\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and
\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.

\membersection{wxSoundFileStream::GetPosition}\label{wxsoundfilestreamgetposition}
\func{wxUint32}{GetPosition}{\void}

It returns the current position in the soundfile stream. The position
is expressed in bytes. If you need the length in seconds, you will need to use
\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and
\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.

\membersection{wxSoundFileStream::SetPosition}\label{wxsoundfilestreamsetposition}
\func{wxUint32}{SetPosition}{\param{wxUint32 }{new\_position}}

It sets the current in the soundfile stream. The position
 {\it new\_position} must be expressed in bytes. You can get
a length/position in bytes from a time value using
\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and 
\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}.

On success, it returns TRUE.

\wxheading{Warning}

Some wxStream may not be capable to support this function as
it may not support the seekable functionnality. If this happens,
it returns FALSE and leave the stream at the same position.

\membersection{wxSoundFileStream::Read}\label{wxsoundfilestreamread}
\func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}

You can obtain the audio data encoded in the file using this function.
But it must be considered as an internal function. Used carelessly, it
may corrupt the current state of the stream.
Data are returned using in the original file coding (You must use a sound
format object to decode it).

\membersection{wxSoundFileStream::Write}\label{wxsoundfilestreamwrite}
\func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}}

You can put encoded audio data to the file using this function.
But it must be considered as an internal function. Used carelessly, it
may corrupt the current state of the stream.
Data must be coded with the specified file coding (You must use a sound
format object to do this).

\membersection{wxSoundFileStream::SetSoundFormat}\label{wxsoundfilestreamsetsoundformat}
\func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}}

\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}

It is called by wxSoundFileStream to prepare the specific file loader
to prepare itself to play the file. Actually, this includes reading
headers and setting the various parameters of the sound format.
This should not be called by an external user but it should be
implemented when you inherit wxSoundFileStream to build a new codec.

It must return when the file is identified and the parameters have
been set. In all other cases, you must return FALSE.

\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}}

This is called by wxSoundFileStream::SetPosition to seek the input stream
to the right position. This must be overidden by the file codec class.
The position is relative to the beginning of the samples.
If it is impossible (as for a piped input stream), you must return FALSE.

\membersection{wxSoundFileStream::FinishPreparation}\label{wxsoundfilestreamfinishpreparation}
\func{void}{FinishPreparation}{\param{wxUint32 }{len}}

This is an internal function but it must called by the file codec class when
the "playing" preparation is finished and you know the size of the stream.
If it is an {\it infinite} stream, you should set this to wxSOUND\_INFINITE\_TIME.

\membersection{wxSoundFileStream::GetData}\label{wxsoundfilestreamgetdata}
\func{wxUint32}{GetData}{\param{void* }{buffer}, \param{wxUint32 }{len}}

This is called by wxSoundFileStream when it needs to get new sound data to
send to the device driver (or to a conversion codec). This must be eventually
overidden by the file codec class. The default behaviour is simply to read from
the input stream.

\membersection{wxSoundFileStream::PutData}\label{wxsoundfilestreamputdata}
\func{wxUint32}{PutData}{\param{const void* }{buffer}, \param{wxUint32 }{len}}

This is called by wxSoundFileStream when it needs to put new sound data received
from the device driver (or from a conversion codec). This must be eventually
overidden by the file codec class. The default behaviour is simply to write to
the input stream.