openal程序员手册.txt

openal三维声音开发包的权威程序员手册

OpenAL程序员手册(一）

OpenAL程序员手册

前言
   本文件来源于因特网,版权归原作者所有.这篇文件的中译版版权归antking所有,如
您对本文件有任何建议,请联系我.([e-mail])

OpenAL 引言

    关于OPENAL的使要围绕在三个对象:Buffer(缓冲器),Sources(声源)和Listener(
听众).缓冲器用于装载数据,然后把它附加在声源上,声源设置并播放.这样,听众就能
根据位置和方向听到声音.建立几个声源和一个听众,然后更改声源的位置和方向.听众
就能听见3D的声音.

加载/卸载

   一个很容易的方法是用alutInit函数,用参数(0,NULL)初始化设备,这样做就避免了
调用OPENAL文本描述.
   如想用EAX,通过名字调用allsExtansionPresent检查EAX,然后用alGetProcAddress
分配变量给函数指针.
   如想用PCM数据的缓冲器用allBufferData,如果PCM数据是以WAV格式存储,alutLoad
WAVFile或alutLoadWAVMen可以恢复它并用alBufferData提供所需的信息.
   对于通常用的声音,可以用alGetError得到错误信息.
   调用alGetSources能得到声源的数量.
   缓冲器附加到声源上用alSourcei.
   在退出程序前用alutExit清除OPENAL.

缓冲器参数

   每个缓冲器是由alGenBuffers附加一个参数引起的.alGenBuffer[f,i]函数用到下面
的参数:
    参数              数据类型              描述
AL_FREQUENCY           i          用Hz表示缓冲器的频率
AL_BITS                i          缓冲器的位深度
AL_CHANIVELS           i          缓冲器的频道数(>1 有效,缓冲器不能在播放时定位)
AL_SIZE                i          用字节表示缓冲器的大小
AL_DATA                i          数据在缓冲器的初始位置

声音参数

   声源由alGenSources加一个参数引起的.函数alSource[f,3f,fv,i]和alSource
[f,3f,fv,i]用于设置和使用下面的声源参数:
    参数              数据类型              描述
AL_PITCH               f          pitch相对总是确定的
AL_GAIN                f          声源获得变量是确定的
AL_MAX_DISTANCE        f          used with the Inverse(lampde distance model
  to set the distance where there will to no
  langer beany attenuation of the source.
AL_ROLLOFF_FACTOR      f          声源的rolloff率,默认的是1.0
AL_REFERENCE_DISTANCE  f          声源的音量在距离上减少一半
AL_MIN_GAIN            f          声音的最小获得
AL_MAX_GAIN            f          声音的最大获得
AL_CONE_OUTER_GAIN     f          在定向的圆锥以外的获得
AL_CONE_INNER_ANGLE    f,i        在定向的圆锥内的获得
AL_CONE_OUTER_ANGLE    f,i        圆锥的角度,默认为360
AL_POSITION            fv,3f      X,Y,Z位置
AL_VELOCITY            fv,3f      速度矢量
AL_DIRECTION           fv,3f      方向矢量
AL_SOURCE_RECATIVE     i          决定位置是否与听众有联系,默认为AL_FLASE
AL_LOOPING             i          设置循环播放(AL_TRUE)或者(AL_FLASE)
AL_BUFFER              i          被附加到声源的缓冲器ID
AL_SOURCE_STATE        i          声源的状态(AL_STOPPED,AL_PLAYING,...)
AL_BUFFERS_QUEUED*     i          队列中声源缓冲器的个数
AL_BUFFERS_PROCESSED*  i          在处理的声源的缓冲器的个数

一个声源的队列缓冲器

    连续的声音不能打断,就需要缓冲器队列.把缓冲器排队,缓冲器和声源用通常的方式
表示,但是alSourcei不能把大量缓冲器附加在声源上.代替它的是函数alSourceQueueBuf
fers和alSourceUnqueueBuffers.函数alSourceQueueBuffers能把一个缓冲器或多个缓冲
器附加在一个声源上,并且能在声源上调用alSourcePlay.到声源在播放时,alSourceUnqu
eueBuffers能释放已播放的缓冲器.这些被留出的缓冲器能用来装载数据或被丢弃.alSou
rceQueueBuffers函数能从新把新的或重新加载的缓冲器附加到播放中的声源.只要有一个
新的缓冲器在队列中播放,那声源就不断的播放.也有一些OPENAL的执行体不能在队列中执
行,可以注意下面的方法:
   1.一个流式的声源用alSourceQueueBuffers附加在缓冲器队列上;
   2.用alSourceQueueBuffers加载的多个缓冲器的源应有相同的声音格式;

Dopple Shift(多普勒效应)

    如果速度应用于听众对象或者任意声源对象,那么,Dopple Shift将运用于声音.在OPE
NAL创造性的执行体上,下面的公式是用于Dopple Shift(多普勒效应):
    DV=AL_DOPPLER_VELOCITY
    DF=AL_DOPPLER_FACTOR
    VI=听众速度
    VS=声源速度
    F=实例速度
    F'=多普勒效应频率
    F'=F*(DV-DF*VI)/(DV+DF*VS).
    多普勒速度用声音的秒数表示,默认为343.如果用分/小表示,那么多普勒速度也相应
改变.
    多普勒因子用于夸大或强调多普勒效应.

错误处理

    alGetError用于表示OPENAL任何时候的错误情况.
    alGetError用于清除OPENAL的错误,因此在重要情况时,应调用alGetError来清除错误.
    错误参数                     描述
AL_NO_ERROR           当前没有任何错误
AL_INVALID_NAME       通过OPENAL函数的一个错误ID
AL_INVALID_ENUM       通过OPENAL函数的一个错误的变量
AL_INVALID_value      通过OPENAL函数的一个错误变量
AL_INVALID_OPERATION  返回操作是错误的
AL_OUT_OF_MEMORY      返回操作结果益出内存

OpenAL程序员手册（二）

核心OPENAL函数

与缓冲器相关
/////////////////////////////////////////////////////
alGenBuffers
描述:
    用于描述一个或多个缓冲器.
函数原型:
    ALvoid alGenBuffers(ALsizei n,ALuint *buffers);
参数:
    n                  缓冲器的个数
    *buffers           指针(用于指向新缓冲器的名字)
返回变量:
    None
评论:
    如果得到的缓冲器数不能建立,alGetError将得到错误.如果错误发生,表示没有缓冲
器建立.如果n为0,表示alGenBuffers没有做任何事,并且没有错误返回.
/////////////////////////////////////////////////////
alDeleteBuffers
描述:
    用于删除一个或多个缓冲器.
函数原型:
    ALvoid alDeleteBuffers(ALsizei n,ALuint *buffers);
参数:
    n                  删除的缓冲器的个数
    *buffer            指针(指向被删除的缓冲器)
返回值:
    None
评论:
    如果返回的缓冲器不能被删除,alGetError将得到错误,如果错误出现,没有缓冲器删
除.如果n等于0,alDeleteBuffers没有做任何事,并且没有错误返回.
/////////////////////////////////////////////////////
allsBuffer
描述:
    测试缓冲器名字的正确性.
函数原型:
    ALboolean  allsBuffer(ALuint  buffer);
参数:
buffer                  用于测试的缓冲器的名字
返回值:
    AL_TRUE 表示正确, AL_FALSE表示错误.
/////////////////////////////////////////////////////
alBufferData
描述:
    用声音数据填充缓冲器.
函数原型:
    ALvoid alBufferData(ALuint buffer,ALenum format,ALvoid *data,ALsizei size,
ALsizei freq);
参数:
buffer                  用于填充的缓冲器的名字
format                  AL_FORMAT_MONO8,AL_FORMAT_MODO16,
AL_FORMAT_STEREO8,AL_FORMAT_STEREO16
*data                   指向声音数据
size                    用字节表示声音数据的大小
freq                    声音数据的频率
返回值:
    None
/////////////////////////////////////////////////////
alGetBufferf
描述:
    用于恢复一个缓冲器的浮点指针.
函数原型:
    ALvoid alGetBufferf(ALuint buffer,ALenum pname,ALfloat *value);
参数:
buffer                  被恢复的缓冲器的名字
pname                   用于恢复的名字
*value                  被恢复数据的浮点指针
返回值:
    None
评论:
    目前没有用于缓冲器的浮点属性.
/////////////////////////////////////////////////////
alGetBufferi
描述:
    用于恢复缓冲器的整数指针.
函数原型:
    ALvoid alGetBufferi(ALuint buffer,ALenum pname,ALint *value);
参数:
buffer                  被恢复的缓冲器的名字
pname                   AL_FREQUENCY,AL_BITS,AL_CHANNELS,AL_SIZE,AL_DATA
*value                  被恢复数据的整数指针
返回值:
    None

OPENAL程序员手册（三）

与声源相关

alGenSources
描述:
    用于产生一个或多个声源.
函数原型:
    ALvoid alGenSources(ALsizei n,ALuint *sources);
参数:
n                       产生的声源的个数
*sources                以整形的方式指向新声源的名字的缓冲器
返回值:
    None
评论:
    如果得到的声源没有建立,那么alGetError将得到错误;如果错误是真的,没有声源
产生;如果n为0,alGenSources没有做任何事,并且没有错误返回.
/////////////////////////////////////////////////////
alDeleteSources
描述:
    用于删除一个或多个声源.
函数原型:
    ALvoid alDeleteSources(ALsizei n,ALuint *sources);
参数:
n                       被删除的声源
*sources                指向被删除的声源
返回值:
    None
评论:
    与上相同.
/////////////////////////////////////////////////////
allsSource
描述:
    测试声源名字是否正确.
函数原型:
    ALboolean allsSource(ALuint source);
参数:
source                  用于测试的声源名字.
返回值:
AL_TRUE,AL_FLASE
/////////////////////////////////////////////////////
alSourcef
描述:
    用于设置声源的浮点指针.
函数原型:
    ALvoid alSourcef(ALuint source,ALenum pname,ALfloat value);
参数:
source                  被设置的声源的名字.
pname                   AL_PITCH,AL_GAIN,AL_MAX_DISTANCE,AL_ROLLOFF_FACTOR,
AL_REFERENCE_DISTANCE,AL_MIN_GAIN,AL_MAN_GAIN,
AL_CONE_OUTER_GAIN
value                   用于设置属性
返回值:
    None
/////////////////////////////////////////////////////
alSourcefv
描述:
    用于设置声源的浮点指针矢量.
函数原型:
    ALvoid alSourcefv(ALuint source,ALenum pname,ALfloat *values);
参数:
source                  被设置的声源的名字
pname                   AL_POSITION,AL_VELOCITY,AL_DIRECTION
*values                 指向矢量
返回值:
    None
评论:
    这个函数取决于函数alSource3f.
/////////////////////////////////////////////////////
alSource3f
描述:
    用3个浮点指针变量设置声源.
函数原型:
    ALvoid alSource3f(ALuint source,ALenum pname,ALfloat v1,ALfloat v2,
      ALfloat v3);
参数:
source                   被设置的声源的名字
pname                    AL_POSITION,AL_VELOCITY,AL_DIRECTION
v1,v2,v3                 三个浮点变量
返回值:
    None
评论:
    这个函数取决于alSourcefv.
/////////////////////////////////////////////////////
alSourcei
描述:
    用于设置声源的整型值
函数原型:
    ALvoid alSourcei(ALuint source,ALenum pname,ALint value);
参数:
source                   用于设置的声源的名字
pname                    AL_SOURCE_RELATIVE,AL_CONE_INTVER_ANGLE,
 AL_CONE_OUTER_ANGLE,AL_LOOPING,AL_BUFFER,
 AL_SOURCE_STATE
value                    用于设置的变量
返回值:
    None
/////////////////////////////////////////////////////
alGetSourcef
描述:
    用于恢复声源的浮点指针值.
函数原型:
    ALvoid alGetSourcef(ALuint source,ALenum pname,ALfloat *value);
参数:
source                   被恢复的声源的名字.
pname                    AL_PITCH,AL_GAIN,AL_MIN_GAIN,AL_MAX_GAIN,AL_NAX_DIST
 ANCE,AL_ROLLOFF_FACTOR,AL_CONE_OUTER_GAIN,AL_CONE_IN
 NER_ANGLE,AL_CONE_OUTER_ANGLE,AL_REFERENCE_DISTANCE
*value                   指向被恢复的浮点指针值
/////////////////////////////////////////////////////
alGetSourcefv
描述:
    用于恢复声源的浮点指针矢量.
函数原型:
    ALvoid alGetSourcefv(ALuint source,ALenum pname,ALfloat *valuts);
参数:
source                    被恢复的声源的名字.
pname                     AL_POSITION,AL_VELOCITY,AL_DIRECTION
*values                   指向被恢复的矢量.
返回值:
    NONE
/////////////////////////////////////////////////////
alGetSourcei
描述:
    用于恢复声源的整型权.
函数原型:
    ALvoid alGetSourcei(ALuint source,ALenum pname,ALint *value);
参数:
source                    被释放的声源的名字.
pname                     AL_SOURCE_RELATIVE,AL_BUFFER,
  AL_SOURCE_STATE,AL_BUFFER_QUEUED
  AL_BUFFERS_PROCESSED
*value                    指向被释放的整型指针.
返回值:
     NONE
/////////////////////////////////////////////////////
alSourcePlay
描述:
    用于播放声音.
函数原型:
    ALvoid alSourcePlay(ALuint source);
参数:
source                    用于播放的声源.
返回值:
    NONE
/////////////////////////////////////////////////////
alSourcePlayv
描述:
    用于播放一系列声源.
函数原型:
    ALvoid alSourcePlayv(ALsizei n,ALuint *sources);
参数:
n                         用于播放的声源的个数.
*sources                  指向一组用于播放的声源.
返回值:
    NONE