]>
Commit | Line | Data |
---|---|---|
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 | ||
13 | Base class for sound streams | |
14 | ||
15 | \wxheading{Derived from} | |
16 | ||
17 | No 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 | |
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 | ||
60 | \begin{verbatim} | |
61 | typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt, | |
62 | void *cdata); | |
63 | \end{verbatim} | |
64 | ||
65 | The {\bf stream} parameter represents the current wxSoundStream. | |
66 | ||
67 | The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}). | |
68 | ||
69 | The {\bf cdata} parameter represents the user callback data which were specified | |
70 | when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}. | |
71 | ||
72 | {\it Note:} There are two other ways to catch sound events: you can inherit the | |
73 | sound 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 | ||
81 | The wxSoundStream object can work in three different modes. These modes are specified | |
82 | at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction} | |
83 | and cannot be changed until you call | |
84 | \helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}. | |
85 | ||
86 | The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT} | |
87 | events and you cannot use wxSoundStream::Write(). | |
88 | ||
89 | The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT} | |
90 | events and you cannot use wxSoundStream::Read(). | |
91 | ||
92 | The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires | |
93 | you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and | |
94 | \helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be | |
95 | careful with realtime problems. Each time you call Read you must call Write. | |
96 | ||
97 | %% | |
98 | %% wxSoundStream events | |
99 | %% | |
100 | ||
101 | \wxheading{wxSoundStream events} | |
102 | ||
103 | The sound events are generated when the sound driver (or the sound stream) completes | |
104 | a previous sound buffer. There are two possible sound events and two meanings. | |
105 | ||
106 | The {\bf wxSOUND\_INPUT} event is generated when the sound stream has a new input | |
107 | buffer ready to be read. You know that you can read a buffer of the size | |
108 | \helpref{GetBestSize()}{wxsoundstreamgetbestsize} without blocking. | |
109 | ||
110 | The {\bf wxSOUND\_OUTPUT} event is generated when the sound stream has completed a | |
111 | previous buffer. This buffer has been sent to the sound driver and it is ready to | |
112 | process a new buffer. Consequently, \helpref{Write}{wxsoundstreamwrite} will not | |
113 | block too. | |
114 | ||
115 | \latexignore{\rtfignore{\wxheading{Members}}} | |
116 | ||
117 | %% Ctor && Dtor | |
118 | ||
119 | \membersection{wxSoundStream::wxSoundStream}\label{wxsoundstreamwxsoundstream} | |
120 | ||
121 | \func{}{wxSoundStream}{\void} | |
122 | ||
123 | Default constructor. | |
124 | ||
125 | \membersection{wxSoundStream::\destruct{wxSoundStream}}\label{wxsoundstreamdtor} | |
126 | ||
127 | \func{}{\destruct{wxSoundStream}}{\void} | |
128 | ||
129 | Destructor. The destructor stops automatically all started production and destroys | |
130 | any 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 | ||
140 | Reads {\it len} bytes from the sound stream. This call may block the user so | |
141 | use it carefully when you need to intensively refresh the GUI. You may be | |
142 | interested by sound events: see \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}. | |
143 | ||
144 | It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the | |
145 | sound event system. | |
146 | ||
147 | \wxheading{Parameters} | |
148 | ||
149 | \docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes | |
150 | and seconds use wxSoundFormat. | |
151 | See \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 | |
154 | stream. 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 | ||
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{Parameters} | |
173 | ||
174 | \docparam{len}{This 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 | \docparam{buffer}{Data in \it{buffer} are coded using the sound format attached to this sound | |
179 | stream. 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 | ||
190 | This function returns the best size for IO calls. The best size provides you | |
191 | a good alignment for data to be written (or read) to (or from) the sound stream. | |
192 | So, when, for example, a sound event is sent, you are sure the sound stream | |
193 | will 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 | ||
203 | SetSoundFormat is one of the key function of the wxSoundStream object. | |
204 | It specifies the sound format the user needs. SetSoundFormat tries to | |
205 | apply the format to the current sound stream (it can be a sound file or a | |
206 | sound driver). Then, either it manages to apply it and it returns {\bf TRUE}, | |
207 | or it could not and it returns {\bf FALSE}. In this case, you must check | |
5d525ad9 JS |
208 | the error with |
209 | \helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See | |
210 | \helpref{wxSoundStream errors section}{wxsoundstream} for more details. | |
e8482f24 GL |
211 | |
212 | \wxheading{Note} | |
213 | ||
214 | The {\bf format} object can be destroyed after the call. The object does not need it. | |
215 | ||
216 | \wxheading{Note} | |
217 | ||
218 | If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best | |
219 | approaching format and setups it. You can check the format which it applied | |
220 | with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}. | |
221 | ||
222 | %% | |
223 | %% GetSoundFormat | |
224 | %% | |
225 | \membersection{wxSoundStream::GetSoundFormat}\label{wxsoundstreamgetsoundformat} | |
226 | \constfunc{wxSoundFormatBase\&}{GetSoundFormat}{\void} | |
227 | ||
228 | It returns a reference to the current sound format of the stream represented by a | |
229 | wxSoundFormatBase object. This object {\it must not} be destroyed by anyone except | |
230 | the 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 | ||
239 | It installs a C callback for wxSoundStream events. The C callbacks are still | |
240 | useful to avoid hard inheritance. You can install only one callback per event. | |
241 | Each 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 | 250 | StartProduction starts the sound streaming. {\it evt} may be one of |
e8482f24 GL |
251 | {\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf wxSOUND\_DUPLEX}. |
252 | You cannot specify several flags at the same time. Starting the production | |
253 | may automaticaly in position of buffer underrun (only in the case you activated | |
254 | recording). Actually this may happen the sound IO queue is too short. | |
255 | It is also advised that you fill quickly enough the sound IO queue when the | |
256 | driver requests it (through a wxSoundEvent). | |
257 | ||
258 | \membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction} | |
5d525ad9 | 259 | |
e8482f24 GL |
260 | \func{bool}{StopProduction}{\void} |
261 | ||
262 | I 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 | ||
268 | Sets 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 | ||
274 | It returns the last error which occured. | |
275 | ||
276 | \membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess} | |
5d525ad9 | 277 | |
e8482f24 GL |
278 | \constfunc{wxUint32}{GetLastAccess}{\void} |
279 | ||
280 | It 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 | ||
286 | It returns whether the sound IO queue is full. When it is full, the next IO call will block | |
287 | until 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 | ||
293 | It is called by the wxSoundStream when a new sound event occured. | |
5d525ad9 | 294 |