Unit CastleALUtils

DescriptionUsesClasses, Interfaces, Objects and RecordsFunctions and ProceduresTypesConstantsVariables

Description

Low-level utilities for working with OpenAL. Everything is based on my OpenAL bindings in unit CastleOpenAL. For higher-level class that takes care of initializing OpenAL and loading and playing sounds, see CastleSoundEngine.

You shouldn't use any alc* functions or alutInit/alutExit functions from CastleOpenAL yourself. This unit and CastleSoundEngine take care about everything needed there.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EOpenALError  
Class EOpenALInitError  
Class EALError Exception for errors reported by alGetError (using constants AL_xxx).
Class TALSoundFile  

Functions and Procedures

procedure CheckALInited;
procedure CheckAL(const situation: string);
function alGetSource1i(SourceName: TALuint; Attribute: TALenum): TALint;
function alGetSource1f(SourceName: TALuint; Attribute: TALenum): TALfloat;
function alGetSource1bool(SourceName: TALuint; Attribute: TALenum): TALboolean;
function alGetSource1ui(SourceName: TALuint; Attribute: TALenum): TALuint;
function alGetSource3f(SourceName: TALuint; Attribute: TALenum): TALVector3f;
function alGetBuffer1sizei(BufferName: TALuint; Attribute: TALenum): TALsizei;
function alGetBuffer1i(BufferName: TALuint; Attribute: TALenum): TALint;
function alGetBuffer1f(BufferName: TALuint; Attribute: TALenum): TALfloat;
function alGetListener1f(Attribute: TALenum): TALfloat;
function alGetListener3f(Attribute: TALenum): TALVector3f;
function alGetListenerOrientation: TALTwoVectors3f;
function alcGetInterger1(deviceHandle:PALCdevice; token:TALenum): TALint;
procedure alSourceVector3f(SourceName: TALuint; Param: TALenum; const Value: TALVector3f);
procedure alListenerVector3f(Param: TALenum; const Value: TALVector3f);
procedure alListenerOrientation(const Dir, Up: TALVector3f); overload;
procedure alListenerOrientation(const Orient: TALTwoVectors3f); overload;
procedure alCreateSources(n: TALsizei; sources: PALuint);
procedure alCreateBuffers(n: TALsizei; buffers: PALuint);
procedure alFreeSource(var Source: TALuint);
procedure alFreeBuffer(var Buffer: TALuint);

Constants

BoolToAL: array[boolean] of TALint = (AL_FALSE, AL_TRUE);

Description

Functions and Procedures

procedure CheckALInited;

Check is ALInited True.

Exceptions raised
EOpenALInitError
If ALInited is False.
procedure CheckAL(const situation: string);
 
Exceptions raised
EALError
if alGetError returned something <> AL_NO_ERROR
function alGetSource1i(SourceName: TALuint; Attribute: TALenum): TALint;

Comfortable wrappers for alGet*. In many cases these should be more comfortable (because they are functions) and safer (no need to pass some pointer) than directly using related OpenAL functions.

OpenAL errors are not checked by these functions (i.e. CheckAL or alGetError is not called).

We don't check does Attribute really return value of given type. This means that if you will request value of the wrong type for given Attribute, OpenAL may do some convertion, or may set the error state. In some cases you may even get nasty access violation errors or accidental writes over some random place in memory — this may happen if for given Attribute OpenAL likes to return an array of some values, and you will use the wrong version (e.g. using AL_GAIN with a version that returns TALVector3f, or using AL_POSITION with a version that returns single TALfloat). So always check carefully that given Attribute supports the requested output value.

function alGetSource1f(SourceName: TALuint; Attribute: TALenum): TALfloat;
 
function alGetSource1bool(SourceName: TALuint; Attribute: TALenum): TALboolean;
 
function alGetSource1ui(SourceName: TALuint; Attribute: TALenum): TALuint;
 
function alGetSource3f(SourceName: TALuint; Attribute: TALenum): TALVector3f;
 
function alGetBuffer1sizei(BufferName: TALuint; Attribute: TALenum): TALsizei;
 
function alGetBuffer1i(BufferName: TALuint; Attribute: TALenum): TALint;
 
function alGetBuffer1f(BufferName: TALuint; Attribute: TALenum): TALfloat;
 
function alGetListener1f(Attribute: TALenum): TALfloat;
 
function alGetListener3f(Attribute: TALenum): TALVector3f;
 
function alGetListenerOrientation: TALTwoVectors3f;
 
function alcGetInterger1(deviceHandle:PALCdevice; token:TALenum): TALint;
 
procedure alSourceVector3f(SourceName: TALuint; Param: TALenum; const Value: TALVector3f);

Comfortable wrappers over OpenAL functions that take vector types. These take TALVector* / TALTwoVectors* types.

Just like with alGet* wrappers (above in this unit), no error checking is done (no CheckAL etc.) and no checking does Param accept the given type of value is done.

procedure alListenerVector3f(Param: TALenum; const Value: TALVector3f);
 
procedure alListenerOrientation(const Dir, Up: TALVector3f); overload;
 
procedure alListenerOrientation(const Orient: TALTwoVectors3f); overload;
 
procedure alCreateSources(n: TALsizei; sources: PALuint);

Allocate OpenAL sources and buffers, making sure their initial state conforms to specification.

Unfortunately current Creative OpenAL Windows implementation violates OpenAL specification: default source state (i.e. newly generated source state) is not as it is specified by OpenAL implementation. Attributes MAX_DISTANCE, DIRECTION and CONE_OUTER_GAIN have different values.

So alCreateSources calls alGenSources and then makes sure that all sources have state consistent with OpenAL specification (under Windows it means that it sets MAX_DISTANCE, DIRECTION and CONE_OUTER_GAIN attributes to their proper values). alCreateBuffers does the same for alGenBuffers (which means, for now, that it simply calls alGenBuffers.)

To be on the safe side, you should always use alCreateSources and alCreateBuffers instead alGenSources and alGenBuffers.

procedure alCreateBuffers(n: TALsizei; buffers: PALuint);
 
procedure alFreeSource(var Source: TALuint);

Pass resource to alDeleteSources or alDeleteBuffers, checking and setting it to zero.

These are trivial wrappers over alDeleteSources(1, @Source), alDeleteBuffers(1, @Buffer). They first check if resource is non-zero, and after freeing set it to zero. This makes calling them many times (e.g. on already freed resources) harmless.

alFreeSource also calls alSourceStop first, because we cannot free playing sources.

procedure alFreeBuffer(var Buffer: TALuint);
 

Constants

BoolToAL: array[boolean] of TALint = (AL_FALSE, AL_TRUE);
 

Generated by PasDoc 0.14.0.