]> git.saurik.com Git - wxWidgets.git/blame - contrib/docs/latex/mmedia/sndbase.tex
Added classinfo macros for wxTreeEvent
[wxWidgets.git] / contrib / docs / latex / mmedia / sndbase.tex
CommitLineData
e8482f24
GL
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
13Base class for sound streams
14
15\wxheading{Derived from}
16
17No 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
35either a driver or a file}
36\twocolitem{{\bf wxSOUND\_INVFRMT}}{The sound format passed to the function is
37invalid. Generally, it means that you passed out of range values to the codec
38stream or you don't pass the right sound format object to the right sound codec
39stream.}
40\twocolitem{{\bf wxSOUND\_INVDEV}}{Invalid device. Generally, it means that the
41sound stream didn't manage to open the device driver due to an invalid parameter
42or 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
44this sound format. It means that the sound driver didn't manage to setup the sound
45card with the specified values.}
46\twocolitem{{\bf wxSOUND\_NOCODEC}}{No matching codec has been found. Generally, it
47may 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
57When a sound event is generated, it may either call the internal sound event
58processor (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
65The {\bf stream} parameter represents the current wxSoundStream.
66
67The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}).
68
69The {\bf cdata} parameter represents the user callback data which were specified
70when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}.
71
72{\it Note:} There are two other ways to catch sound events: you can inherit the
73sound 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
81The wxSoundStream object can work in three different modes. These modes are specified
82at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction}
83and cannot be changed until you call
84\helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}.
85
86The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT}
87events and you cannot use wxSoundStream::Write().
88
89The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT}
90events and you cannot use wxSoundStream::Read().
91
92The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires
93you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and
94\helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be
95careful with realtime problems. Each time you call Read you must call Write.
96
97%%
98%% wxSoundStream events
99%%
100
101\wxheading{wxSoundStream events}
102
103The sound events are generated when the sound driver (or the sound stream) completes
104a previous sound buffer. There are two possible sound events and two meanings.
105
106The {\bf wxSOUND\_INPUT} event is generated when the sound stream has a new input
107buffer ready to be read. You know that you can read a buffer of the size
108\helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking.
109
110The {\bf wxSOUND\_OUTPUT} event is generated when the sound stream has completed a
111previous buffer. This buffer has been sent to the sound driver and it is ready to
112process a new buffer. Consequently, \helpref{Write}{wxsoundstreamwrite} will not
113block too.
114
115\latexignore{\rtfignore{\wxheading{Members}}}
116
117%% Ctor && Dtor
118
119\membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream}
120
121\func{}{wxSoundStream}{\void}
122
123Default constructor.
124
125\membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor}
126
127\func{}{\destruct{wxSoundStream}}{\void}
128
129Destructor. The destructor stops automatically all started production and destroys
130any 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
140Reads {\it len} bytes from the sound stream. This call may block the user so
141use it carefully when you need to intensively refresh the GUI. You may be
142interested by sound events: see \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
143
144It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
145sound event system.
146
147\wxheading{Parameters}
148
149\docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes
150and seconds use wxSoundFormat.
151See \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
154stream. 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
165Writes \it{len} bytes to the sound stream. This call may block the user so
166use it carefully. You may be interested by sound events: see
167\helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
168
169It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
170sound event system.
171
172\wxheading{Parameters}
173
174\docparam{len}{This is expressed in bytes. If you need to do conversions between bytes
175and seconds use wxSoundFormat.
176See \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
179stream. 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
190This function returns the best size for IO calls. The best size provides you
191a good alignment for data to be written (or read) to (or from) the sound stream.
192So, when, for example, a sound event is sent, you are sure the sound stream
193will 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
203SetSoundFormat is one of the key function of the wxSoundStream object.
204It specifies the sound format the user needs. SetSoundFormat tries to
205apply the format to the current sound stream (it can be a sound file or a
206sound driver). Then, either it manages to apply it and it returns {\bf TRUE},
207or it could not and it returns {\bf FALSE}. In this case, you must check
5d525ad9
JS
208the error with
209\helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
210\helpref{wxSoundStream errors section}{wxsoundstream} for more details.
e8482f24
GL
211
212\wxheading{Note}
213
214The {\bf format} object can be destroyed after the call. The object does not need it.
215
216\wxheading{Note}
217
218If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best
219approaching format and setups it. You can check the format which it applied
220with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
221
222%%
223%% GetSoundFormat
224%%
225\membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat}
226\constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void}
227
228It returns a reference to the current sound format of the stream represented by a
229wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except
230the stream itself.
231
232%%
233%% SetCallback
234%%
235\membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister}
236
237\func{void}{Register}{\param{int }{evt}, \param{wxSoundCallback }{cbk}, \param{void* }{cdata}}
238
239It installs a C callback for wxSoundStream events. The C callbacks are still
240useful to avoid hard inheritance. You can install only one callback per event.
241Each callback has its callback data.
242
243%%
244%% StartProduction
245%%
246\membersection{wxSoundStream::StartProduction}\label{wxsoundstreamstartproduction}
247
248\func{bool}{StartProduction}{\param{int }{evt}}
249
5d525ad9 250StartProduction starts the sound streaming. {\it evt} may be one of
e8482f24
GL
251{\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf wxSOUND\_DUPLEX}.
252You cannot specify several flags at the same time. Starting the production
253may automaticaly in position of buffer underrun (only in the case you activated
254recording). Actually this may happen the sound IO queue is too short.
255It is also advised that you fill quickly enough the sound IO queue when the
256driver requests it (through a wxSoundEvent).
257
258\membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction}
5d525ad9 259
e8482f24
GL
260\func{bool}{StopProduction}{\void}
261
262I stops the async notifier and the sound streaming straightly.
263
264\membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler}
5d525ad9 265
e8482f24
GL
266\func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}}
267
268Sets the event handler: if it is non-null, all events are routed to it.
269
270\membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror}
5d525ad9 271
e8482f24
GL
272\constfunc{wxSoundError}{GetError}{\void}
273
274It returns the last error which occured.
275
276\membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
5d525ad9 277
e8482f24
GL
278\constfunc{wxUint32}{GetLastAccess}{\void}
279
280It returns the number of bytes which were effectively written to/read from the sound stream.
281
282\membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled}
5d525ad9 283
e8482f24
GL
284\constfunc{bool}{QueueFilled}{\void}
285
286It returns whether the sound IO queue is full. When it is full, the next IO call will block
287until the IO queue has at least one empty entry.
288
289\membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent}
5d525ad9 290
e8482f24
GL
291\func{void}{OnSoundEvent}{\param{int }{evt}}
292
293It is called by the wxSoundStream when a new sound event occured.
5d525ad9 294