OpenAL Programmer's Guide
OpenAL Versions 1.0 and 1.1
- 1 -
Copyright ©2007 by Creative Technology Limited
All rights reserved.
Trademarks and Service Marks
Creative, Sound Blaster, Sound Blaster X-Fi, and the Creative logo are registered trademarks,
and Environmental Audio, EAX, and the Environmental Audio Extensions logo are trademarks of
Creative Technology Ltd. in the United States and/or other countries.
All other brands and product names listed are trademarks or registered trademarks of their
respective holders.
Acknowledgments
Documentation written by Garin Hiebert. Additional input by Keith Charley, Peter Harrison, Jean-
Marc Jot, Daniel Peacock, Jean-Michel Trivi, and Carlo Vogelsang.
Revision History
Revision 1.0 October 2005 Garin Hiebert
Revision 1.1 July 2006 Garin Hiebert
Revision 1.2 December 2006 Garin Hiebert
Revision 1.3 March 2007 Peter Harrison
Revision 1.4 June 2007 Peter Harrison
Revision 1.5 June 2007 Daniel Peacock
- 2 -
Table of Contents
TABLE OF CONTENTS.................................................................................................................. 3
ABOUT THIS DOCUMENT............................................................................................................. 7
INTRODUCTION............................................................................................................................... 7
INTENDED AUDIENCE ...................................................................................................................... 7
OTHER OPENAL RESOURCES......................................................................................................... 7
INTRODUCTION TO OPENAL....................................................................................................... 8
OBJECTS ....................................................................................................................................... 8
DEVICE ENUMERATION ................................................................................................................... 8
INITIALIZING/EXITING ...................................................................................................................... 9
LISTENER PROPERTIES................................................................................................................. 11
BUFFER PROPERTIES ................................................................................................................... 12
SOURCE PROPERTIES .................................................................................................................. 12
QUEUING BUFFERS ON A SOURCE................................................................................................. 14
DOPPLER SHIFT ........................................................................................................................... 14
ERROR HANDLING ........................................................................................................................ 16
EXTENSIONS ................................................................................................................................16
BUFFER FUNCTIONS.................................................................................................................. 17
PROPERTIES ................................................................................................................................17
FUNCTIONS .................................................................................................................................. 17
alGenBuffers........................................................................................................................... 18
alDeleteBuffers....................................................................................................................... 19
alIsBuffer ................................................................................................................................20
alBufferData............................................................................................................................ 21
alBufferf .................................................................................................................................. 22
alBuffer3f ................................................................................................................................23
alBufferfv ................................................................................................................................24
alBufferi .................................................................................................................................. 25
alBuffer3i ................................................................................................................................26
alBufferiv................................................................................................................................. 27
alGetBufferf ............................................................................................................................ 28
alGetBuffer3f .......................................................................................................................... 29
alGetBufferfv........................................................................................................................... 30
alGetBufferi............................................................................................................................. 31
alGetBuffer3i........................................................................................................................... 32
alGetBufferiv........................................................................................................................... 33
SOURCE FUNCTIONS ................................................................................................................. 34
PROPERTIES ................................................................................................................................34
FUNCTIONS .................................................................................................................................. 34
alGenSources......................................................................................................................... 36
alDeleteSources..................................................................................................................... 37
alIsSource............................................................................................................................... 38
alSourcef ................................................................................................................................39
alSource3f .............................................................................................................................. 40
alSourcefv............................................................................................................................... 41
alSourcei................................................................................................................................. 42
alSource3i............................................................................................................................... 43
alSourceiv............................................................................................................................... 44
alGetSourcef........................................................................................................................... 45
alGetSource3f......................................................................................................................... 46
alGetSourcefv......................................................................................................................... 47
- 3 -
alGetSourcei........................................................................................................................... 48
alGetSource3i......................................................................................................................... 49
alGetSourceiv......................................................................................................................... 50
alSourcePlay .......................................................................................................................... 51
alSourcePlayv......................................................................................................................... 52
alSourcePause....................................................................................................................... 53
alSourcePausev ..................................................................................................................... 54
alSourceStop.......................................................................................................................... 55
alSourceStopv........................................................................................................................ 56
alSourceRewind ..................................................................................................................... 57
alSourceRewindv ................................................................................................................... 58
alSourceQueueBuffers........................................................................................................... 59
alSourceUnqueueBuffers....................................................................................................... 60
LISTENER FUNCTIONS............................................................................................................... 61
PROPERTIES ................................................................................................................................61
FUNCTIONS .................................................................................................................................. 61
alListenerf............................................................................................................................... 62
alListener3f............................................................................................................................. 63
alListenerfv............................................................................................................................. 64
alListeneri............................................................................................................................... 65
alListener3i............................................................................................................................. 66
alListeneriv ............................................................................................................................. 67
alGetListenerf......................................................................................................................... 68
alGetListener3f....................................................................................................................... 69
alGetListenerfv ....................................................................................................................... 70
alGetListeneri ......................................................................................................................... 71
alGetListener3i ....................................................................................................................... 72
alGetListeneriv........................................................................................................................ 73
STATE FUNCTIONS..................................................................................................................... 74
PROPERTIES ................................................................................................................................74
FUNCTIONS .................................................................................................................................. 74
alEnable.................................................................................................................................. 75
alDisable................................................................................................................................. 76
alIsEnabled............................................................................................................................. 77
alGetBoolean.......................................................................................................................... 78
alGetDouble............................................................................................................................ 79
alGetFloat............................................................................................................................... 80
alGetInteger............................................................................................................................ 81
alGetBooleanv........................................................................................................................ 82
alGetDoublev.......................................................................................................................... 83
alGetFloatv............................................................................................................................. 84
alGetIntegerv.......................................................................................................................... 85
alGetString.............................................................................................................................. 86
alDistanceModel..................................................................................................................... 87
alDopplerFactor...................................................................................................................... 91
alSpeedOfSound.................................................................................................................... 92
ERROR FUNCTIONS.................................................................................................................... 93
ERROR CODES............................................................................................................................. 93
FUNCTIONS .................................................................................................................................. 93
alGetError............................................................................................................................... 94
EXTENSION FUNCTIONS............................................................................................................ 95
FUNCTIONS .................................................................................................................................. 95
alIsExtensionPresent.............................................................................................................. 96
- 4 -
alGetProcAddress .................................................................................................................. 97
alGetEnumValue .................................................................................................................... 98
CONTEXT MANAGEMENT FUNCTIONS.................................................................................... 99
PROPERTIES ................................................................................................................................99
FUNCTIONS .................................................................................................................................. 99
alcCreateContext.................................................................................................................. 100
alcMakeContextCurrent........................................................................................................ 101
alcProcessContext ............................................................................................................... 102
alcSuspendContext .............................................................................................................. 103
alcDestroyContext................................................................................................................ 104
alcGetCurrentContext........................................................................................................... 105
alcGetContextsDevice.......................................................................................................... 106
CONTEXT ERROR FUNCTIONS ............................................................................................... 107
ERROR CODES........................................................................................................................... 107
FUNCTIONS ................................................................................................................................ 107
alcGetError........................................................................................................................... 108
CONTEXT DEVICE FUNCTIONS............................................................................................... 109
FUNCTIONS ................................................................................................................................ 109
alcOpenDevice..................................................................................................................... 110
alcCloseDevice..................................................................................................................... 111
CONTEXT EXTENSION FUNCTIONS........................................................................................ 112
FUNCTIONS ................................................................................................................................ 112
alcIsExtensionPresent.......................................................................................................... 113
alcGetProcAddress .............................................................................................................. 114
alcGetEnumValue ................................................................................................................ 115
CONTEXT STATE FUNCTIONS................................................................................................. 116
FUNCTIONS ................................................................................................................................ 116
alcGetString.......................................................................................................................... 117
alcGetIntegerv...................................................................................................................... 118
CONTEXT CAPTURE FUNCTIONS........................................................................................... 119
FUNCTIONS ................................................................................................................................ 119
alcCaptureOpenDevice ........................................................................................................ 120
alcCaptureCloseDevice........................................................................................................ 121
alcCaptureStart..................................................................................................................... 122
alcCaptureStop..................................................................................................................... 123
alcCaptureSamples.............................................................................................................. 124
ALC AND AL FUNCTION LISTS................................................................................................ 125
ALC FUNCTIONS ........................................................................................................................ 125
AL FUNCTIONS........................................................................................................................... 125
STANDARD EXTENSIONS TO OPENAL.................................................................................. 127
ENUMERATION EXTENSION ......................................................................................................... 128
Detecting the Enumeration Extension.................................................................................. 128
Retrieving device names...................................................................................................... 128
Parsing the device string...................................................................................................... 129
Checking the current device name....................................................................................... 129
Enumeration Names............................................................................................................. 129
CREATIVE LABS’ EXTENSIONS TO OPENAL ........................................................................ 131
ENUMERATE ALL EXTENSION ...................................................................................................... 132
- 5 -