Castle Game Engine: CastleALUtils

# Unit CastleALUtils
Description | Uses | Classes, Interfaces, Objects and Records | Functions and Procedures | Types | Constants | Variables
## 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 SysUtils CastleUtils CastleOpenAL Classes CastleSoundFile CastleTimeUtils ## 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.13.0 on 2013-08-17 21:27:12