OpenAL 1.1 Specification and Reference
Specification and Reference
This is the OpenAL 1.1 Specification and Reference. This document is based upon the older OpenAL Specification and Reference (1.0), published in June 2000. Both copyright notices are presented below.
Version 1.1
Published June 2005
Copyright © 2005 by authors
Version 1.0 Draft Edition
Published June 2000
Copyright © 1999-2000 by Loki Software
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the copyright owners.
BeOS is a trademark of PalmSource, Inc.
Linux is a trademark of Linus Torvalds.
Macintosh and Apple are trademarks of Apple Computer, Inc.
OpenAL is a trademark of Creative Labs, Inc.
OpenGL is a trademark of Silicon Graphics, Inc.
UNIX is a trademark of X/Open Group.
Windows is a trademark of Microsoft Corp.
X Window System is a trademark of X Consortium, Inc.
All other trademarks are property of their respective owners.
Table of Contents
1.1. Revision History, 1.1 Document 7
1.2. A Brief History of OpenAL 8
1.3. What Is the OpenAL Audio System? 8
1.4. Differences Between OpenAL 1.1 and OpenAL 1.0 9
1.4.1. Recording API 9
1.4.2. Get/Set Offset 9
1.4.3. Linear Distance Models 9
1.4.4. Exponential Distance Models 9
1.4.5. Doppler 9
1.4.6. Mono/Stereo Hints 9
1.4.7. Standard Extensions Listings 9
1.4.8. Standard Suspend/Process Behavior 10
1.4.9. ALUT Revisions 10
1.4.10. Streaming Clarifications 10
1.4.11. Error Codes 10
1.4.12. Pitch Shifting Limits 10
1.4.13. New ALchar and ALCchar types 10
1.4.14. alcCloseDevice Return Value 10
1.4.15. Versioning Changes 10
1.5. Programmer's View of OpenAL 10
1.6. Implementor's View of OpenAL 11
1.7. Our View 11
1.8. Requirements, Conformance and Extensions 11
1.9. Architecture Review and Acknowledgments 12
2.1. OpenAL Fundamentals 13
2.2. Primitive Types 13
2.3. Floating-Point Computation 14
2.4. AL State 14
2.5. AL Command Syntax 15
2.6. Basic AL Operation 15
2.7. AL Errors 16
2.8. Controlling AL Execution 18
2.9. Object Paradigm 18
2.9.1. Object Categories 18
2.10. Static vs. Dynamic Objects 18
2.11. Object Names 19
2.12. Requesting Object Names 19
2.13. Releasing Object Names 19
2.14. Validating an Object Name 20
2.15. Setting Object Attributes 20
2.16. Querying Object Attributes 21
2.17. Object Attributes 22
3. State and State Requests 23
3.1. Querying OpenAL State 23
3.1.1. Simple Queries 23
3.1.2. String Queries 24
3.2. Time and Frequency 24
3.3. Space and Distance 24
3.4. Attenuation By Distance 25
3.4.1. Inverse Distance Rolloff Model 26
3.4.2. Inverse Distance Clamped Model 26
3.4.3. Linear Distance Rolloff Model 26
3.4.4. Linear Distance Clamped Model 26
3.4.5. Exponential Distance Rolloff Model 27
3.4.6. Exponential Distance Clamped Model 27
3.5. Evaluation of Gain/Attenuation Related State 27
3.5.1. No Culling By Distance 28
3.5.2. Velocity Dependent Doppler Effect 28
4.1. Basic Listener and Source Attributes 31
4.2. Listener Object 32
4.2.1. Listener Attributes 32
4.2.2. Changing Listener Attributes 33
4.2.3. Querying Listener Attributes 33
4.3. Source Objects 33
4.3.1. Managing Source Names 33
Requesting a Source Name 33
Releasing Source Names 34
Validating a Source Name 34
4.3.2. Source Attributes 34
Source Positioning 34
Source Type 34
Buffer Looping 35
Current Buffer 35
Queue State Queries 36
Bounds on Gain 36
Distance Model Attributes 37
Frequency Shift by Pitch 38
Direction and Cone 38
Offset 40
4.3.3. Changing Source Attributes 41
4.3.4. Querying Source Attributes 41
4.3.5. Queuing Buffers with a Source 41
Queuing Command 42
Unqueuing Command 42
4.3.6. Managing Source Execution 43
Source State Query 43
State Transition Commands 43
Resetting Configuration 45
5. Buffers 46
5.1. Buffer States 46
5.2. Managing Buffer Names 47
5.2.1. Requesting Buffers Names 47
5.2.2. Releasing Buffer Names 47
5.2.3. Validating a Buffer Name 47
5.3. Manipulating Buffer Attributes 47
5.3.1. Buffer Attributes 47
5.3.2. Changing Buffer Attributes 48
5.3.3. Querying Buffer Attributes 49
5.3.4. Specifying Buffer Content 49
6. AL Contexts and the ALC API 51
6.1. Managing Devices 51
6.1.1. Connecting to a Device 51
6.1.2. Disconnecting from a Device 51
6.2. Managing Rendering Contexts 51
6.2.1. Context Attributes 52
6.2.2. Creating a Context 52
6.2.3. Selecting a Context for Operation 53
6.2.4. Initiate Context Processing 53
6.2.5. Suspend Context Processing 53
6.2.6. Destroying a Context 54
6.3. ALC Queries 54
6.3.1. Query for Current Context 54
6.3.2. Query for a Context's Device 54
6.3.3. Query For Extensions 54
6.3.4. Query for Function Entry Addresses 54
6.3.5. Retrieving Enumeration Values 55
6.3.6. Query for Error Conditions 55
6.3.7. String Query 56
6.3.8. Integer Query 57
6.4. Shared Objects 57
6.4.1. Shared Buffers 58
6.4.2. Capture 58
Procedures and Functions 58
Tokens 58
Audio capture 59
7.1. Extension Query 61
7.2. Retrieving Function Entry Addresses 61
7.3. Retrieving Enumeration Values 61
8. Appendix: Extension Process 63
9. Appendix: 1.0-Compatible Extensions 64
9.1. ALC_EXT_CAPTURE 64
9.2. AL_EXT_OFFSET 64
9.3. AL_EXT_LINEAR_DISTANCE 65
9.4. AL_EXT_EXPONENT_DISTANCE 65
9.5. ALC_ENUMERATION_EXT 65