ALContext Class Reference

Inherits from	NSObject
Conforms to	OALSuspendManager
Declared in	ALContext.h

Overview

A context encompasses a single listener and a series of sources. A context is created from a device, and many contexts may be created (though multiple contexts would be unusual in an iOS app).

Note: Some property values are only valid if this context is the current context.

Tasks

alVersion
OpenAL version string in format “[spec major number].[spec minor number] [optional vendor version information]” Only valid when this is the current context.
property
attributes
The current context’s attribute list. Only valid when this is the current context.
property
context
The OpenAL context pointer.
property
device
The device this context was opened on.
property
distanceModel
The current distance model. Legal values are AL_NONE, AL_INVERSE_DISTANCE, AL_INVERSE_DISTANCE_CLAMPED, AL_LINEAR_DISTANCE, AL_LINEAR_DISTANCE_CLAMPED, AL_EXPONENT_DISTANCE, and AL_EXPONENT_DISTANCE_CLAMPED. See the OpenAL spec for detailed information.
Only valid when this is the current context.
property
dopplerFactor
Exaggeration factor for Doppler effect. Only valid when this is the current context.
property
extensions
List of available extensions (NSString*). Only valid when this is the current context.
property
listener
This context’s listener.
property
renderer
Information about the specific renderer. Only valid when this is the current context.
property
sources
All sources associated with this context (ALSource*).
property
speedOfSound
Speed of sound in same units as velocities. Only valid when this is the current context.
property
vendor
Name of the vendor. Only valid when this is the current context.
property
+ contextOnDevice:attributes:
Create a new context on the specified device.
+ contextOnDevice:outputFrequency:refreshIntervals:synchronousContext:monoSources:stereoSources:
Create a new context on the specified device with attributes.
– initOnDevice:outputFrequency:refreshIntervals:synchronousContext:monoSources:stereoSources:
Initialize this context on the specified device with attributes.
– initOnDevice:attributes:
Initialize this context for the specified device and attributes.
– process
Process this context.
– stopAllSounds
Stop all sound sources in this context.
– clearBuffers
Clear all buffers being used by sources in this context.
– ensureContextIsCurrent
Make sure this context is the current context. This method is used to work around iOS 4.0 and 4.2 bugs that could cause the context to be lost.
– isExtensionPresent:
Check if the specified extension is present in this context. Only valid when this is the current context.
– getProcAddress:
Get the address of the specified procedure (C function address). Only valid when this is the current context.
Note: The OpenAL implementation is free to return a pointer even if it is not valid for this context. Always call isExtensionPresent first.
– notifySourceInitializing:
(INTERNAL USE) Used by ALSource to announce initialization.
– notifySourceDeallocating:
(INTERNAL USE) Used by ALSource to announce deallocation.

Properties

alVersion

OpenAL version string in format “[spec major number].[spec minor number] [optional vendor version information]” Only valid when this is the current context.

@property (nonatomic, readonly) NSString *alVersion

Declared In

ALContext.h

attributes

The current context’s attribute list. Only valid when this is the current context.

@property (nonatomic, readonly) NSArray *attributes

Declared In

ALContext.h

context

The OpenAL context pointer.

@property (nonatomic, readonly) ALCcontext *context

Declared In

ALContext.h

device

The device this context was opened on.

@property (nonatomic, readonly) ALDevice *device

Declared In

ALContext.h

distanceModel

The current distance model. Legal values are AL_NONE, AL_INVERSE_DISTANCE, AL_INVERSE_DISTANCE_CLAMPED, AL_LINEAR_DISTANCE, AL_LINEAR_DISTANCE_CLAMPED, AL_EXPONENT_DISTANCE, and AL_EXPONENT_DISTANCE_CLAMPED. See the OpenAL spec for detailed information.
Only valid when this is the current context.

@property (readwrite, assign) ALenum distanceModel

Declared In

ALContext.h

dopplerFactor

Exaggeration factor for Doppler effect. Only valid when this is the current context.

@property (readwrite, assign) float dopplerFactor

Declared In

ALContext.h

extensions

List of available extensions (NSString*). Only valid when this is the current context.

@property (nonatomic, readonly) NSArray *extensions

Declared In

ALContext.h

listener

This context’s listener.

@property (nonatomic, readonly) ALListener *listener

Declared In

ALContext.h

renderer

Information about the specific renderer. Only valid when this is the current context.

@property (nonatomic, readonly) NSString *renderer

Declared In

ALContext.h

sources

All sources associated with this context (ALSource*).

@property (nonatomic, readonly) NSArray *sources

Declared In

ALContext.h

speedOfSound

Speed of sound in same units as velocities. Only valid when this is the current context.

@property (readwrite, assign) float speedOfSound

Declared In

ALContext.h

vendor

Name of the vendor. Only valid when this is the current context.

@property (nonatomic, readonly) NSString *vendor

Declared In

ALContext.h

Class Methods

contextOnDevice:attributes:

Create a new context on the specified device.

+ (id)contextOnDevice:(ALDevice *)device attributes:(NSArray *)attributes

Parameters

device: The device to open the context on.

attributes: An array of NSNumber in ordered pairs (attribute id followed by integer value). Posible attributes: ALC_FREQUENCY, ALC_REFRESH, ALC_SYNC, ALC_MONO_SOURCES, ALC_STEREO_SOURCES

Return Value

A new context.

Declared In

ALContext.h

contextOnDevice:outputFrequency:refreshIntervals:synchronousContext:monoSources:stereoSources:

Create a new context on the specified device with attributes.

+ (id)contextOnDevice:(ALDevice *)device outputFrequency:(int)outputFrequency refreshIntervals:(int)refreshIntervals synchronousContext:(bool)synchronousContext monoSources:(int)monoSources stereoSources:(int)stereoSources

Parameters

device: The device to open the context on.

outputFrequency: The frequency to mix all sources to before outputting (ignored by iOS).

refreshIntervals: The number of passes per second used to mix the audio sources. For games this can be 5-15. For audio intensive apps, it should be higher (ignored by iOS).

synchronousContext: If true, this context runs on the main thread and depends on you calling alcUpdateContext (ignored by iOS).

monoSources: A hint indicating how many sources should support mono (default 28 on iOS).

stereoSources: A hint indicating how many sources should support stereo (default 4 on iOS).

Return Value

A new context.

Declared In

ALContext.h

Instance Methods

clearBuffers

Clear all buffers being used by sources in this context.

- (void)clearBuffers

Declared In

ALContext.h

ensureContextIsCurrent

Make sure this context is the current context. This method is used to work around iOS 4.0 and 4.2 bugs that could cause the context to be lost.

- (void)ensureContextIsCurrent

Declared In

ALContext.h

getProcAddress:

Get the address of the specified procedure (C function address). Only valid when this is the current context.
Note: The OpenAL implementation is free to return a pointer even if it is not valid for this context. Always call isExtensionPresent first.

- (void *)getProcAddress:(NSString *)functionName

Parameters

functionName: the name of the procedure to get.

Return Value

the procedure’s address, or NULL if it wasn’t found.

Declared In

ALContext.h

initOnDevice:attributes:

Initialize this context for the specified device and attributes.

- (id)initOnDevice:(ALDevice *)device attributes:(NSArray *)attributes

Parameters

device: The device to open the context on.

attributes: An array of NSNumber in ordered pairs (attribute id followed by integer value). Posible attributes: ALC_FREQUENCY, ALC_REFRESH, ALC_SYNC, ALC_MONO_SOURCES, ALC_STEREO_SOURCES

Return Value

The initialized context.

Declared In

ALContext.h

initOnDevice:outputFrequency:refreshIntervals:synchronousContext:monoSources:stereoSources:

Initialize this context on the specified device with attributes.

- (id)initOnDevice:(ALDevice *)device outputFrequency:(int)outputFrequency refreshIntervals:(int)refreshIntervals synchronousContext:(bool)synchronousContext monoSources:(int)monoSources stereoSources:(int)stereoSources

Parameters

device: The device to open the context on.

outputFrequency: The frequency to mix all sources to before outputting (ignored by iOS).

refreshIntervals: The number of passes per second used to mix the audio sources. For games this can be 5-15. For audio intensive apps, it should be higher (ignored by iOS).

synchronousContext: If true, this context runs on the main thread and depends on you calling alcUpdateContext (ignored by iOS).

monoSources: A hint indicating how many sources should support mono (default 28 on iOS).

stereoSources: A hint indicating how many sources should support stereo (default 4 on iOS).

Return Value

The initialized context.

Declared In

ALContext.h

isExtensionPresent:

Check if the specified extension is present in this context. Only valid when this is the current context.

- (bool)isExtensionPresent:(NSString *)name

Parameters

name: The name of the extension to check.

Return Value

TRUE if the extension is present in this context.

Declared In

ALContext.h

notifySourceDeallocating:

(INTERNAL USE) Used by ALSource to announce deallocation.

- (void)notifySourceDeallocating:(ALSource *)source

Parameters

source: the source that is deallocating.

Declared In

ALContext.h

notifySourceInitializing:

(INTERNAL USE) Used by ALSource to announce initialization.

- (void)notifySourceInitializing:(ALSource *)source

Parameters

source: the source that is initializing.

Declared In

ALContext.h

process

Process this context.

- (void)process

Declared In

ALContext.h

stopAllSounds

Stop all sound sources in this context.

- (void)stopAllSounds

Declared In

ALContext.h