Source

pygame / doc / src / openalbase.xml

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.openal.base">
  <alias>pygame2.openal</alias>
  <short>basic OpenAL wrapper module</short>
  <desc>
    .. todo::
    
       detailled description of the OpenAL model, including contexts, devices,
       source and listener bindings and the context/state driven behaviour.
    
    Type identifiers for the property get and set methods:
    
    +------+------------------------------------------------------------+
    | 'b'  | Get or set a single boolean value (e.g. AL_TRUE)           |
    +------+------------------------------------------------------------+
    | 'ba' | Get or set an array of boolean values. The array can be    |
    |      | any type of sequence containing matching values.           |
    +------+------------------------------------------------------------+
    | 'i'  | Get or set a single integer value.                         |
    +------+------------------------------------------------------------+
    | 'i3' | Get or set an triplet of integer values. The array can be  |
    |      | any type of sequence containing matching values.           |
    +------+------------------------------------------------------------+
    | 'ia' | Get or set an array of integer values. The array can be    |
    |      | any type of sequence containing matching values.           |
    +------+------------------------------------------------------------+
    | 'f'  | Get or set a single floating point value.                  |
    +------+------------------------------------------------------------+
    | 'f3' | Get or set an triplet of floating point values. The array  |
    |      | can be any type of sequence containing matching values.    |
    +------+------------------------------------------------------------+
    | 'fa' | Get or set an array of floating point values. The array    |
    |      | can be any type of sequence containing matching values.    |
    +------+------------------------------------------------------------+
    | 'd'  | Get or set a single double precision floating point value. |
    +------+------------------------------------------------------------+
    | 'da' | Get or set an array of double precision floating point     |
    |      | values. The array can be any type of sequence containing   |
    |      | matching values.                                           |
    +------+------------------------------------------------------------+
  </desc>

  <class name="Buffers">
    <constructor>Buffers () -> NotImplementedError</constructor>
    <desc>
      Buffers objects are used by OpenAL to buffer and provide PCM data
      for playback, recording and manipulation.
      
      The Buffers object provides methods and properties to manipulate
      certain aspects of the buffered data and can be queued to multiple
      Sources within the same context.

      Buffers instances cannot be created directly, but are bound to a
      :class:`Device`. To create a Buffers instance for the currently
      active :class:`Device`, use the :meth:`Context.create_buffers` method
      on the currently active :class:`Context`.
    </desc>
    <example></example>
    <method name="buffer_data">
      <call>buffer_data (bufnum, format, data, samplerate) -> None</call>
      <desc>Buffers a chunk of *data* into one of the created buffers.
      
        Buffers a chunk of PCM *data* into the buffer at *bufnum*. *format*
        describes the audio format of the data (see
        :mod:`pygame2.openal.constants` for
        more details). *samplerate* denotes the sample rate in Hz.
      </desc>
      <example></example>
    </method>
    <attr name="buffers">
      <desc>Gets the buffer identifiers used in the Buffers instance.</desc>
      <example></example>
    </attr>
    <attr name="count">
      <desc>Gets the number of buffers managed in the Buffers instance.</desc>
      <example></example>
    </attr>
    <method name="get_prop">
      <call>get_prop (bufnum, prop, type) -> value or (value, ...) </call>
      <desc>Retrieves the value(s) of an OpenAL property for the Buffers.
      
        Retrieves the value or values of a buffer-related OpenAL property for
        the buffer identified by *bufnum*. *prop* can be any valid buffer
        constant and *type* **must** be a valid value type identifier for the
        constant.
      </desc>
      <example></example>
    </method>
    <method name="set_prop">
      <call>set_prop (bufnum, prop, value[,type]) -> None</call>
      <desc>Sets the value(s) of an OpenAL property for the Buffers.
      
        Sets the value or values of a buffer-related OpenAL property for the 
        buffer identified by *bufnum*. *prop* can be any valid buffer
        constant, while *value* **must** be valid for the constant.
        
        If *type* is omitted, the function tries to guess, which type should be
        used from the passed value(s). Guessing tries to convert values
        implicitly, where possible, so if there are ambiguous values, it is
        better to provide *type*.
      </desc>
      <example></example>
    </method>
  </class>

  <class name="CaptureDevice">
    <constructor>CaptureDevice (frequency, format, bufsize) -> CaptureDevice
    CaptureDevice (name, frequency, format, bufsize) -> CaptureDevice
    </constructor>
    <desc>Creates a sound capturing device.
    
    The CaptureDevice acts as recorder for a certain hardware device and
    allows the caller to record incoming sound samples (e.g. from a
    microphone or line-in device).

    The captured samples will be stored in an internal buffer, which is
    guaranteed to hold *bufsize* samples. Depending on the passed
    *format* and *frequency*, captured samples can vary in their byte
    size (see :mod:`pygame2.openal.constants` for more details) and
    speed of occurance.
    </desc>
    <example></example>
    <attr name="format">
      <desc>Gets the set audio format for the CaptureDevice.</desc>
      <example></example>
    </attr>
    <attr name="frequency">
      <desc>Gets the set frequency in Hz for the CaptureDevice.</desc>
      <example></example>
    </attr>
    <method name="get_samples">
      <call>get_samples ([buffer]) -> (str or bytes) or int</call>
      <desc>Retrieves the available samples from the CaptureDevice.

      Retrieves the samples that are available on the CaptureDevice. If
      a *buffer* is provided, the samples will be directly written to
      the buffer and the amount of bytes written will be returned.

      If no *buffer* is provided, the retrieved samples will be returned
      as byte sequence (byte string or string).
      </desc>
      <example></example>
    </method>
    <attr name="size">
      <desc>Gets the default buffer size for the CaptureDevice.</desc>
      <example></example>
    </attr>
    <method name="start">
      <call>start () ->None</call>
      <desc>Starts capturing incoming samples on the device.

      Starts capturing incoming samples for the CaptureDevice. The
      samples will be stored in the CaptureDevice's internal buffer. If
      the buffer is full, the oldest samples will be overwritten with
      the newest samples (ring buffer).
      </desc>
      <example></example>
    </method>
    <method name="stop">
      <call>stop () -> None</call>
      <desc>Stops capturing incoming samples.</desc>
      <example></example>
    </method>
  </class>

  <class name="Context">
    <constructor>Context (device[,attribtes]) -> Context</constructor>
    <desc>Creates a new Context for a specific Device.
    
      OpenAL contexts represent logical state groups, where
      :class:`Sources` and a :class:`Listener` are managed and audio
      data is correctly streamed to the underlying output
      :class:`Device`.

      Contexts can be created for multiple devices and independently
      managed without influencing each other. To be processed correctly
      at a certain time, a :class:`Context` must be set as the *current*
      one in OpenAL. This will cause OpenAL to process only data from
      that :class:`Context` to and from the audio hardware.

      Most methods and properties will fail for a :class:`Context` that
      is not marked as the *current* one. So before accessing any member
      of a :class:`Context`, make sure, you marked it as *current*.
    </desc>
    <example></example>
    <method name="create_buffers">
      <call>create_buffers (amount) -> Buffers</call>
      <desc>Creates a Buffers instance with *amount* buffers for the Context.
      </desc>
      <example></example>
    </method>
    <method name="create_sources">
      <call>create_sources (amount) -> Sources</call>
      <desc>Creates a Sources instance with *amount* sources for the Context.
      </desc>
      <example></example>
    </method>
    <attr name="device">
      <desc>Gets the :class:`Device` the Context is using.</desc>
      <example></example>
    </attr>
    <method name="disable">
      <call>disable (value) -> None</call>
      <desc>Disables a certain context-specific setting.</desc>
      <example></example>
    </method>
    <attr name="distance_model">
      <desc>Gets or sets the distance model setting for the
      :class:`Context`.</desc>
      <example></example>
    </attr>
    <attr name="doppler_factor">
      <desc>Gets or sets the doppler factor setting for the
      :class:`Context`.</desc>
      <example></example>
    </attr>
    <method name="enable">
      <call>enable (value) -> None</call>
      <desc>Enables a certain context-specific setting.</desc>
      <example></example>
    </method>
    <attr name="is_current">
      <desc>Gets, whether the :class:`Context` is marked the current one
      to process.</desc>
      <example></example>
    </attr>
    <method name="is_enabled">
      <call>is_enabled (value) -> bool</call>
      <desc>Checks, whether a certain setting is enabled.</desc>
      <example></example>
    </method>
    <attr name="listener">
      <desc>Gets the :class:`Listener` for the :class:`Context`.</desc>
      <example></example>
    </attr>
    <method name="make_current">
      <call>make_current () -> bool</call>
      <desc>Tries to mark the :class:`Context` as current.
      
        Tries to mark the :class:`Context` as the current one. If the
        :class:`Context` could not be marked sucessfully, False will be
        returned, otherwise True.

        Any other :class:`Context`, which was previously marked as
        current, will loose this state.
      </desc>
      <example></example>
    </method>
    <method name="process">
      <call>process () -> None</call>
      <desc>Processes the :class:`Context`.
      
        Processes the :class:`Context`, causing it to update any
        internal states, stream audio data to and from the hardware,
        update the internal source and listener positions and so forth.
      </desc>
      <example></example>
    </method>
    <attr name="speed_of_sound">
      <desc>Gets or sets the value of the speed of sound for the
      :class:`Context`.</desc>
      <example></example>
    </attr>
    <method name="suspend">
      <call>suspend () -> None</call>
      <desc>Suspends the :class:`Context` from processing any data.</desc>
      <example></example>
    </method>
  </class>

  <class name="Device">
    <constructor>Device ([name]) -> Device</constructor>
    <desc>Creates a sound output device.

    The Device class acts as sound streaming sink, by default for
    playing audio data (The :class:`CaptureDevice` also inherits from
    :class:`Device`, but acts as recorder).
    </desc>
    <example></example>
    <attr name="extensions">
      <desc>Gets a list of available extensions for the Device and
      OpenAL implementation.
      </desc>
      <example></example>
    </attr>
    <method name="get_enum_value">
      <call>get_enum_value (name) -> long</call>
      <desc>Gets the value of a Device-specific OpenAL enumeration name.
      </desc>
      <example></example>
    </method>
    <method name="get_error">
      <call>get_error () -> str</call>
      <desc>
        Gets the last OpenAL error message occured on the Device.

        OpenAL devices maintain an internal error message. This message
        will usually be given to you when a :exc:`pygame2.Error` is
        raised.

        You will rarely need to call this function.
      
        .. note::
        
          Once called, the internal error message will be cleared, so
          that subsequent calls of this function will return *None*,
          until a new error occurs.
    </desc>
      <desc></desc>
      <example></example>
    </method>
    <method name="has_extension">
      <call>has_extension (extname) -> bool</call>
      <desc>Checks, whether a certain extension is available on the Device.
      </desc>
      <example></example>
    </method>
    <attr name="name">
      <desc>Gets the name of the Device as reported by OpenAL.</desc>
      <example></example>
    </attr>
  </class>

  <class name="Listener">
    <constructor>Listener () -> NotImplementedError</constructor>
    <desc>
      The Listener represents the user hearing the sounds played by OpenAL in a
      specific Context. Source playback is done relative to the position of the
      Listener in the 3D space.
    
      Listener instances cannot be created directly, but are bound to a
      :class:`Context`. To create (or get) a Listener instance for the
      currently active :class:`Context`, use the :attr:`Context.listener`
      property.
    </desc>
    <example></example>
    <method name="get_prop">
      <call>get_prop (prop, type) -> value or (value, ...)</call>
      <desc>Retrieves the value(s) of an OpenAL property for the Listener.
      
        Retrieves the value or values of a listener-related OpenAL property.
        *prop* can be any valid listener constant and *type* **must** be a
        valid value type identifier for the constant.
      </desc>
      <example></example>
    </method>
    <method name="set_prop">
      <call>set_prop (prop, value[, type]) -> None</call>
      <desc>Sets the value(s) of an OpenAL property for the Listener.
      
        Sets the value or values of a listener-related OpenAL property.
        *prop* can be any valid listener constant, while *value* **must** be
        valid for the constant.
        
        If *type* is omitted, the function tries to guess, which type should be
        used from the passed value(s). Guessing tries to convert values
        implicitly, where possible, so if there are ambiguous values, it is
        better to provide *type*.
      </desc>
      <example></example>
    </method>
  </class>

  <class name="Sources">
    <constructor>Sources () -> NotImplementedError</constructor>
    <desc>
      Sources store locations, directions, and other attributes of an object in
      3D space and have a buffer associated with them for playback. When the
      program wants to play a sound, it controls execution through a source
      object. Sources are processed independently from each other.
      
      Sources instances cannot be created directly, but are bound to a
      :class:`Context`. To create a Sources instance for the currently
      active :class:`Context`, use the :meth:`Context.create_sources` method.
    </desc>
    <example></example>
    <attr name="count">
      <desc>Gets the number of sources managed in the Sources instance.</desc>
      <example></example>
    </attr>
    <method name="get_prop">
      <call>get_prop (sourcenum, prop, type) -> value or (value, ...)</call>
      <desc>Retrieves the value(s) of an OpenAL property for the Sources.
      
        Retrieves the value or values of a sources-related OpenAL property for
        the source identified by *sourcenum*. *prop* can be any valid source
        constant and *type* **must** be a valid value type identifier for the
        constant.
      </desc>
      <example></example>
    </method>
    <method name="pause">
      <call>pause (sourcenum) -> None
        pause ((sourcenum1, sourcenum2, ...)) -> None
      </call>
      <desc>Pauses a single source or a set of sources.
      
        Pauses a single source identified by *sourcenum* or a set of sources
        identified by the passed sequence of source identifiers.
      </desc>
      <example></example>
    </method>
    <method name="play">
      <call>play (sourcenum) -> None
        play ((sourcenum1, sourcenum2, ...)) -> None
      </call>
      <desc>Plays a single source or a set of sources.
      
        Plays a single source identified by *sourcenum* or a set of sources
        identified by the passed sequence of source identifiers.
      </desc>
      <example></example>
    </method>
    <method name="queue_buffers">
      <call>queue_buffers (sourcenum, buffers) -> None</call>
      <desc>Queues a :class:`Buffers` on a source.

        Queues a :class:`Buffers` instance holding one or multiple audio buffers
        on the source identified by *sourcenum*. The audio buffers in *buffers*
        will be played in sequence.
        
        To retrieve the number of audio buffers already processed, you can query
        the source with the :const:`AL_BUFFERS_PROCESSED` constant.
      </desc>
      <example></example>
    </method>
    <method name="rewind">
      <call>rewind (sourcenum) -> None
        rewind ((sourcenum1, sourcenum2, ...)) -> None
      </call>
      <desc>Rewinds a single source or a set of sources.
      
        Rewinds a single source identified by *sourcenum* or a set of sources
        identified by the passed sequence of source identifiers.
      </desc>
      <example></example>
    </method>
    <method name="set_prop">
      <call>set_prop (sourcenum, prop, value[, type]) -> None</call>
      <desc>Sets the value(s) of an OpenAL property for the Sources.
      
        Sets the value or values of a sources-related OpenAL property for the 
        source identified by *sourcenum*. *prop* can be any valid source
        constant, while *value* **must** be valid for the constant.
        
        If *type* is omitted, the function tries to guess, which type should be
        used from the passed value(s). Guessing tries to convert values
        implicitly, where possible, so if there are ambiguous values, it is
        better to provide *type*.
      </desc>
      <example></example>
    </method>
    <attr name="sources">
      <desc>Gets the source identifiers used in the Sources instance.</desc>
      <example></example>
    </attr>
    <method name="stop">
      <call>stop (sourcenum) -> None
        stop ((sourcenum1, sourcenum2, ...)) -> None
      </call>
      <desc>Stops playing a single source or a set of sources.
      
        Stops playing a single source identified by *sourcenum* or a set of
        sources identified by the passed sequence of source identifiers.
      </desc>
      <example></example>
    </method>
    <method name="unqueue_buffers">
      <call>unqueue_buffers (sourcenum, buffers) -> None</call>
      <desc>Unqueues processed :class:`Buffers` from a source
      
        Unqueus an already processed :class:`Buffers` with one or multiple audio
        buffers from the source identified by *sourcenum*.
        
        .. note::
        
          This will only succeed, when all buffers within the :class:`Buffers`
          instance were processed by the source. Otherwise a
          :exc:`pygame2.Error` will be raised.
      </desc>
      <example></example>
    </method>
  </class>

  <func name="al_get_string">
    <call>al_get_string (prop) -> str</call>
    <desc>Retrieves an OpenAL string property.
    
      For valid property values, see :mod:`pygame2.openal.constants`.
    </desc>
    <example>
      import pygame2.openal as openal
      import pygame2.openal.constants as const
      
      print (openal.al_get_string (const.AL_VENDOR))
    </example>
  </func>
  <func name="get_default_capture_device_name">
    <call>get_default_capture_device_name () -> str</call>
    <desc>Gets the name of the default capture device.</desc>
    <example></example>
  </func>
  <func name="get_default_output_device_name">
    <call>get_default_output_device_name () -> str</call>
    <desc>Gets the name of the default output device.</desc>
    <example></example>
  </func>
  <func name="get_enum_value">
    <call>get_enum_value (name) -> long</call>
    <desc>Gets the value of an OpenAL enumeration name.</desc>
    <example></example>
  </func>
  <func name="get_error">
    <call>get_error () -> str</call>
    <desc>
      Gets the last OpenAL error message occured.

      OpenAL maintains an internal error message. This message will usually
      be given to you when a :exc:`pygame2.Error` is raised.

      You will rarely need to call this function.
      
      .. note::
        
        Once called, the internal OpenAL error message will be cleared, so that
        subsequent calls of this function will return *None*, until a new
        OpenAL error occurs.
    </desc>
    <example></example>
  </func>
  <func name="init">
    <call>init ()</call>
    <desc>Initializes the underlying OpenAL library.

      .. note::    
        
        This function is currently only available for compliance with other
        pygame2 modules, but does not actually perform anything. The behaviour
        might change in later pygame2 versions, so it is generally safe to call
        this function.
    </desc>
    <example></example>
  </func>
  <func name="is_extension_present">
    <call>is_extension_present (name[, device]) -> bool</call>
    <desc>Checks, whether the specified extension is available.
    
      Checks, whether the extension specified by *name* is available in the
      current OpenAL implementation. If a *device* is passed, the OpenAL's
      :pygame2.openal.Device` will be checked for the extension.
    </desc>
    <example></example>
  </func>
  <func name="list_capture_devices">
    <call>list_capture_devices () -> [str, str, ...]</call>
    <desc>Retrieves a list of available capture devices.
    
      Retrieves a list of available and supported capture device names. If no
      capture devices could be found, an empty list is returned.
    </desc>
    <example></example>
  </func>
  <func name="list_output_devices">
    <call>list_output_devices</call>
    <desc>Retrieves a list of available output devices.
    
      Retrieves a list of available and supported output device names. If no
      output devices could be found, an empty list is returned.
    </desc>
    <example></example>
  </func>
  <func name="quit">
    <call>quit ()</call>
    <desc>Shuts down the underlying OpenAL library.
    
      .. note::    
        
        This function is currently only available for compliance with other
        pygame2 modules, but does not actually perform anything. The behaviour
        might change in later pygame2 versions, so it is generally safe to call
        this function.
    </desc>
    <example></example>
  </func>
  <func name="set_current_context">
    <call>set_current_context (context) -> bool</call>
    <desc>Switches the current OpenAL context.
    
      Switches the current OpenAL context. The current OpenAL context can then
      be influenced in various ways, such as attaching sources, buffers and
      tweaking its settings.
      
      Returns True, if the context could be switched successfully, otherwise
      False.
    </desc>
    <example></example>
  </func>
</module>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.