treeform / openal

An OpenAL wrapper for nim.

Nim OpenAL wrapper

nimble install openal

API reference

This library has no dependencies other than the Nim standard library.

About

An OpenAL wrapper for nim. OpenAL is a cross platform way to play sounds.

OpenAL works on:

• Windows
• macOS
• Linux

Its great for games because it can play sounds in 3d and apply effects to them.

Great reference on how to use openAL:

https://github.com/kcat/openal-soft/wiki/Programmer's-Guide

Small example on how to use this nim library:

import openal, os, readwav

var
  # sound by DANMITCH3LL: https://freesound.org/people/DANMITCH3LL/sounds/232009/
  wav = readWav("xylophone-sweep.wav") # read wav file using simple helper utility
  buffer = ALuint(0) # buffer is like a record of a sound
  source = ALuint(0) # source is like a record player, it can play 1 buffer at a time

# open setup and error handling
let device = alcOpenDevice(nil)
if device == nil: quit "OpenAL: failed to get default device"
let ctx = device.alcCreateContext(nil)
if ctx == nil: quit "OpenAL: failed to create context"
if not alcMakeContextCurrent(ctx): quit "OpenAL: failed to make context current"

# setup buffer
alGenBuffers(ALsizei 1, addr buffer)
alBufferData(buffer, AL_FORMAT_MONO16, wav.data, ALsizei wav.size, ALsizei wav.freq)

# setup source
alGenSources(ALsizei 1, addr source)
alSourcei(source, AL_BUFFER, Alint buffer)
alSourcePlay(source)

# wait for sound to finish playing
sleep(2500)

# taredown and error handling
alDeleteSources(1, addr source)
alDeleteBuffers(1, addr buffer)
alcDestroyContext(ctx)
if not alcCloseDevice(device): quit "OpenAL: failed to close device"

API: openal

import openal

type ALuint

ALuint = cuint

type ALint

ALint = cint

type ALsizei

ALsizei = cint

type ALenum

ALenum = cint

type ALfloat

ALfloat = float32

type ALdouble

ALdouble = float64

const AL_SOURCE_RELATIVE

AL_SOURCE_RELATIVE = 0x00000202

const AL_CONE_INNER_ANGLE

AL_CONE_INNER_ANGLE = 0x00001001

const AL_CONE_OUTER_ANGLE

AL_CONE_OUTER_ANGLE = 0x00001002

const AL_PITCH

AL_PITCH = 0x00001003

const AL_POSITION

AL_POSITION = 0x00001004

const AL_DIRECTION

AL_DIRECTION = 0x00001005

const AL_VELOCITY

AL_VELOCITY = 0x00001006

const AL_LOOPING

AL_LOOPING = 0x00001007

const AL_BUFFER

AL_BUFFER = 0x00001009

const AL_GAIN

AL_GAIN = 0x0000100A

const AL_MIN_GAIN

AL_MIN_GAIN = 0x0000100D

const AL_MAX_GAIN

AL_MAX_GAIN = 0x0000100E

const AL_ORIENTATION

AL_ORIENTATION = 0x0000100F

const AL_SOURCE_STATE

AL_SOURCE_STATE = 0x00001010

const AL_INITIAL

AL_INITIAL = 0x00001011

const AL_PLAYING

AL_PLAYING = 0x00001012

const AL_PAUSED

AL_PAUSED = 0x00001013

const AL_STOPPED

AL_STOPPED = 0x00001014

const AL_BUFFERS_QUEUED

AL_BUFFERS_QUEUED = 0x00001015

const AL_BUFFERS_PROCESSED

AL_BUFFERS_PROCESSED = 0x00001016

const AL_SEC_OFFSET

AL_SEC_OFFSET = 0x00001024

const AL_SAMPLE_OFFSET

AL_SAMPLE_OFFSET = 0x00001025

const AL_BYTE_OFFSET

AL_BYTE_OFFSET = 0x00001026

const AL_SOURCE_TYPE

AL_SOURCE_TYPE = 0x00001027

const AL_STATIC

AL_STATIC = 0x00001028

const AL_STREAMING

AL_STREAMING = 0x00001029

const AL_UNDETERMINED

AL_UNDETERMINED = 0x00001030

const AL_FORMAT_MONO8

AL_FORMAT_MONO8 = 0x00001100

const AL_FORMAT_MONO16

AL_FORMAT_MONO16 = 0x00001101

const AL_FORMAT_STEREO8

AL_FORMAT_STEREO8 = 0x00001102

const AL_FORMAT_STEREO16

AL_FORMAT_STEREO16 = 0x00001103

const AL_REFERENCE_DISTANCE

AL_REFERENCE_DISTANCE = 0x00001020

const AL_ROLLOFF_FACTOR

AL_ROLLOFF_FACTOR = 0x00001021

const AL_CONE_OUTER_GAIN

AL_CONE_OUTER_GAIN = 0x00001022

const AL_MAX_DISTANCE

AL_MAX_DISTANCE = 0x00001023

const AL_FREQUENCY

AL_FREQUENCY = 0x00002001

const AL_BITS

AL_BITS = 0x00002002

const AL_CHANNELS

AL_CHANNELS = 0x00002003

const AL_SIZE

AL_SIZE = 0x00002004

const AL_UNUSED

AL_UNUSED = 0x00002010

const AL_PENDING

AL_PENDING = 0x00002011

const AL_PROCESSED

AL_PROCESSED = 0x00002012

const AL_NO_ERROR

AL_NO_ERROR = false

const AL_INVALID_NAME

AL_INVALID_NAME = 0x0000A001

const AL_INVALID_ENUM

AL_INVALID_ENUM = 0x0000A002

const AL_INVALID_VALUE

AL_INVALID_VALUE = 0x0000A003

const AL_INVALID_OPERATION

AL_INVALID_OPERATION = 0x0000A004

const AL_OUT_OF_MEMORY

AL_OUT_OF_MEMORY = 0x0000A005

const AL_VENDOR

AL_VENDOR = 0x0000B001

const AL_VERSION

AL_VERSION = 0x0000B002

const AL_RENDERER

AL_RENDERER = 0x0000B003

const AL_EXTENSIONS

AL_EXTENSIONS = 0x0000B004

const AL_DOPPLER_FACTOR

AL_DOPPLER_FACTOR = 0x0000C000

const AL_DOPPLER_VELOCITY

AL_DOPPLER_VELOCITY = 0x0000C001

const AL_SPEED_OF_SOUND

AL_SPEED_OF_SOUND = 0x0000C003

const AL_DISTANCE_MODEL

AL_DISTANCE_MODEL = 0x0000D000

const AL_INVERSE_DISTANCE

AL_INVERSE_DISTANCE = 0x0000D001

const AL_INVERSE_DISTANCE_CLAMPED

AL_INVERSE_DISTANCE_CLAMPED = 0x0000D002

const AL_LINEAR_DISTANCE

AL_LINEAR_DISTANCE = 0x0000D003

const AL_LINEAR_DISTANCE_CLAMPED

AL_LINEAR_DISTANCE_CLAMPED = 0x0000D004

const AL_EXPONENT_DISTANCE

AL_EXPONENT_DISTANCE = 0x0000D005

const AL_EXPONENT_DISTANCE_CLAMPED

AL_EXPONENT_DISTANCE_CLAMPED = 0x0000D006

const AL_PRIORITY

AL_PRIORITY = 0x0000E001

const AL_PRIORITY_SLOTS

AL_PRIORITY_SLOTS = 0x0000E002

proc alEnable

proc alEnable(capability: ALenum) {.cdecl, importc.}

proc alDisable

proc alDisable(capability: ALenum) {.cdecl, importc.}

proc alIsEnabled

proc alIsEnabled(capability: ALenum): bool {.cdecl, importc.}

proc alGetString

proc alGetString(param: ALenum): ptr char {.cdecl, importc.}

proc alGetBooleanv

proc alGetBooleanv(param: ALenum; data: ptr bool) {.cdecl, importc.}

proc alGetIntegerv

proc alGetIntegerv(param: ALenum; data: ptr ALint) {.cdecl, importc.}

proc alGetFloatv

proc alGetFloatv(param: ALenum; data: ptr ALfloat) {.cdecl, importc.}

proc alGetDoublev

proc alGetDoublev(param: ALenum; data: ptr ALdouble) {.cdecl, importc.}

proc alGetBoolean

proc alGetBoolean(param: ALenum): bool {.cdecl, importc.}

proc alGetInteger

proc alGetInteger(param: ALenum): ALint {.cdecl, importc.}

proc alGetFloat

proc alGetFloat(param: ALenum): ALfloat {.cdecl, importc.}

proc alGetDouble

proc alGetDouble(param: ALenum): ALdouble {.cdecl, importc.}

proc alGetError

proc alGetError(): ALenum {.cdecl, importc.}

proc alIsExtensionPresent

proc alIsExtensionPresent(extname: ptr char): bool {.cdecl, importc.}

proc alGetProcAddress

proc alGetProcAddress(fname: ptr char): pointer {.cdecl, importc.}

proc alGetEnumValue

proc alGetEnumValue(ename: ptr char): ALenum {.cdecl, importc.}

proc alListenerf

proc alListenerf(param: ALenum; value: ALfloat) {.cdecl, importc.}

proc alListener3f

proc alListener3f(param: ALenum; value1: ALfloat; value2: ALfloat; value3: ALfloat) {.cdecl, importc.}

proc alListenerfv

proc alListenerfv(param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alListeneri

proc alListeneri(param: ALenum; value: ALint) {.cdecl, importc.}

proc alListener3i

proc alListener3i(param: ALenum; value1: ALint; value2: ALint; value3: ALint) {.cdecl, importc.}

proc alListeneriv

proc alListeneriv(param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alGetListenerf

proc alGetListenerf(param: ALenum; value: ptr ALfloat) {.cdecl, importc.}

proc alGetListener3f

proc alGetListener3f(param: ALenum; value1: ptr ALfloat; value2: ptr ALfloat;
                    value3: ptr ALfloat) {.cdecl, importc.}

proc alGetListenerfv

proc alGetListenerfv(param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alGetListeneri

proc alGetListeneri(param: ALenum; value: ptr ALint) {.cdecl, importc.}

proc alGetListener3i

proc alGetListener3i(param: ALenum; value1: ptr ALint; value2: ptr ALint;
                    value3: ptr ALint) {.cdecl, importc.}

proc alGetListeneriv

proc alGetListeneriv(param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alGenSources

proc alGenSources(n: ALsizei; sources: ptr ALuint) {.cdecl, importc.}

proc alDeleteSources

proc alDeleteSources(n: ALsizei; sources: ptr ALuint) {.cdecl, importc.}

proc alIsSource

proc alIsSource(sid: ALuint): bool {.cdecl, importc.}

proc alSourcef

proc alSourcef(sid: ALuint; param: ALenum; value: ALfloat) {.cdecl, importc.}

proc alSource3f

proc alSource3f(sid: ALuint; param: ALenum; value1: ALfloat; value2: ALfloat;
               value3: ALfloat) {.cdecl, importc.}

proc alSourcefv

proc alSourcefv(sid: ALuint; param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alSourcei

proc alSourcei(sid: ALuint; param: ALenum; value: ALint) {.cdecl, importc.}

proc alSource3i

proc alSource3i(sid: ALuint; param: ALenum; value1: ALint; value2: ALint; value3: ALint) {.cdecl, importc.}

proc alSourceiv

proc alSourceiv(sid: ALuint; param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alGetSourcef

proc alGetSourcef(sid: ALuint; param: ALenum; value: ptr ALfloat) {.cdecl, importc.}

proc alGetSource3f

proc alGetSource3f(sid: ALuint; param: ALenum; value1: ptr ALfloat; value2: ptr ALfloat;
                  value3: ptr ALfloat) {.cdecl, importc.}

proc alGetSourcefv

proc alGetSourcefv(sid: ALuint; param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alGetSourcei

proc alGetSourcei(sid: ALuint; param: ALenum; value: ptr ALint) {.cdecl, importc.}

proc alGetSource3i

proc alGetSource3i(sid: ALuint; param: ALenum; value1: ptr ALint; value2: ptr ALint;
                  value3: ptr ALint) {.cdecl, importc.}

proc alGetSourceiv

proc alGetSourceiv(sid: ALuint; param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alSourcePlayv

proc alSourcePlayv(ns: ALsizei; sids: ptr ALuint) {.cdecl, importc.}

proc alSourceStopv

proc alSourceStopv(ns: ALsizei; sids: ptr ALuint) {.cdecl, importc.}

proc alSourceRewindv

proc alSourceRewindv(ns: ALsizei; sids: ptr ALuint) {.cdecl, importc.}

proc alSourcePausev

proc alSourcePausev(ns: ALsizei; sids: ptr ALuint) {.cdecl, importc.}

proc alSourcePlay

proc alSourcePlay(sid: ALuint) {.cdecl, importc.}

proc alSourceStop

proc alSourceStop(sid: ALuint) {.cdecl, importc.}

proc alSourceRewind

proc alSourceRewind(sid: ALuint) {.cdecl, importc.}

proc alSourcePause

proc alSourcePause(sid: ALuint) {.cdecl, importc.}

proc alSourceQueueBuffers

proc alSourceQueueBuffers(sid: ALuint; numEntries: ALsizei; bids: ptr ALuint) {.cdecl, importc.}

proc alSourceUnqueueBuffers

proc alSourceUnqueueBuffers(sid: ALuint; numEntries: ALsizei; bids: ptr ALuint) {.cdecl, importc.}

proc alGenBuffers

proc alGenBuffers(n: ALsizei; buffers: ptr ALuint) {.cdecl, importc.}

proc alDeleteBuffers

proc alDeleteBuffers(n: ALsizei; buffers: ptr ALuint) {.cdecl, importc.}

proc alIsBuffer

proc alIsBuffer(bid: ALuint): bool {.cdecl, importc.}

proc alBufferData

proc alBufferData(bid: ALuint; format: ALenum; data: pointer; size: ALsizei;
                 freq: ALsizei) {.cdecl, importc.}

proc alBufferf

proc alBufferf(bid: ALuint; param: ALenum; value: ALfloat) {.cdecl, importc.}

proc alBuffer3f

proc alBuffer3f(bid: ALuint; param: ALenum; value1: ALfloat; value2: ALfloat;
               value3: ALfloat) {.cdecl, importc.}

proc alBufferfv

proc alBufferfv(bid: ALuint; param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alBufferi

proc alBufferi(bid: ALuint; param: ALenum; value: ALint) {.cdecl, importc.}

proc alBuffer3i

proc alBuffer3i(bid: ALuint; param: ALenum; value1: ALint; value2: ALint; value3: ALint) {.cdecl, importc.}

proc alBufferiv

proc alBufferiv(bid: ALuint; param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alGetBufferf

proc alGetBufferf(bid: ALuint; param: ALenum; value: ptr ALfloat) {.cdecl, importc.}

proc alGetBuffer3f

proc alGetBuffer3f(bid: ALuint; param: ALenum; value1: ptr ALfloat; value2: ptr ALfloat;
                  value3: ptr ALfloat) {.cdecl, importc.}

proc alGetBufferfv

proc alGetBufferfv(bid: ALuint; param: ALenum; values: ptr ALfloat) {.cdecl, importc.}

proc alGetBufferi

proc alGetBufferi(bid: ALuint; param: ALenum; value: ptr ALint) {.cdecl, importc.}

proc alGetBuffer3i

proc alGetBuffer3i(bid: ALuint; param: ALenum; value1: ptr ALint; value2: ptr ALint;
                  value3: ptr ALint) {.cdecl, importc.}

proc alGetBufferiv

proc alGetBufferiv(bid: ALuint; param: ALenum; values: ptr ALint) {.cdecl, importc.}

proc alDopplerFactor

proc alDopplerFactor(value: ALfloat) {.cdecl, importc.}

proc alDopplerVelocity

proc alDopplerVelocity(value: ALfloat) {.cdecl, importc.}

proc alSpeedOfSound

proc alSpeedOfSound(value: ALfloat) {.cdecl, importc.}

proc alDistanceModel

proc alDistanceModel(distanceModel: ALenum) {.cdecl, importc.}

const ALCAPI

ALCAPI = true

const ALCAPIENTRY

ALCAPIENTRY = true

const ALC_INVALID

ALC_INVALID = 0

const ALC_VERSION_0_1

ALC_VERSION_0_1 = 1

type ALCchar

ALCchar = char

type ALCbyte

ALCbyte = cchar

type ALCubyte

ALCubyte = cuchar

type ALCshort

ALCshort = cshort

type ALCushort

ALCushort = cushort

type ALCint

ALCint = cint

type ALCuint

ALCuint = cuint

type ALCsizei

ALCsizei = cint

type ALCenum

ALCenum = cint

type ALCfloat

ALCfloat = cfloat

type ALCdouble

ALCdouble = cdouble

type ALCdevice

ALCdevice = pointer

type ALCcontext

ALCcontext = pointer

const ALC_FALSE

ALC_FALSE = 0

const ALC_TRUE

ALC_TRUE = 1

const ALC_FREQUENCY

ALC_FREQUENCY = 0x00001007

const ALC_REFRESH

ALC_REFRESH = 0x00001008

const ALC_SYNC

ALC_SYNC = 0x00001009

const ALC_MONO_SOURCES

ALC_MONO_SOURCES = 0x00001010

const ALC_STEREO_SOURCES

ALC_STEREO_SOURCES = 0x00001011

const ALC_NO_ERROR

ALC_NO_ERROR = 0

const ALC_INVALID_DEVICE

ALC_INVALID_DEVICE = 0x0000A001

const ALC_INVALID_CONTEXT

ALC_INVALID_CONTEXT = 0x0000A002

const ALC_INVALID_ENUM

ALC_INVALID_ENUM = 0x0000A003

const ALC_INVALID_VALUE

ALC_INVALID_VALUE = 0x0000A004

const ALC_OUT_OF_MEMORY

ALC_OUT_OF_MEMORY = 0x0000A005

const ALC_DEFAULT_DEVICE_SPECIFIER

ALC_DEFAULT_DEVICE_SPECIFIER = 0x00001004

const ALC_DEVICE_SPECIFIER

ALC_DEVICE_SPECIFIER = 0x00001005

const ALC_EXTENSIONS

ALC_EXTENSIONS = 0x00001006

const ALC_MAJOR_VERSION

ALC_MAJOR_VERSION = 0x00001000

const ALC_MINOR_VERSION

ALC_MINOR_VERSION = 0x00001001

const ALC_ATTRIBUTES_SIZE

ALC_ATTRIBUTES_SIZE = 0x00001002

const ALC_ALL_ATTRIBUTES

ALC_ALL_ATTRIBUTES = 0x00001003

const ALC_CAPTURE_DEVICE_SPECIFIER

ALC_CAPTURE_DEVICE_SPECIFIER = 0x00000310

const ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER

ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER = 0x00000311

const ALC_CAPTURE_SAMPLES

ALC_CAPTURE_SAMPLES = 0x00000312

proc alcCreateContext

proc alcCreateContext(device: ALCdevice; attrlist: ptr ALCint): ALCcontext {.cdecl, importc.}

proc alcMakeContextCurrent

proc alcMakeContextCurrent(context: ALCcontext): bool {.cdecl, importc.}

proc alcProcessContext

proc alcProcessContext(context: ALCcontext) {.cdecl, importc.}

proc alcSuspendContext

proc alcSuspendContext(context: ALCcontext) {.cdecl, importc.}

proc alcDestroyContext

proc alcDestroyContext(context: ALCcontext) {.cdecl, importc.}

proc alcGetCurrentContext

proc alcGetCurrentContext(): ALCcontext {.cdecl, importc.}

proc alcGetContextsDevice

proc alcGetContextsDevice(context: ALCcontext): ALCdevice {.cdecl, importc.}

proc alcOpenDevice

proc alcOpenDevice(devicename: ptr ALCchar): ALCdevice {.cdecl, importc.}

proc alcCloseDevice

proc alcCloseDevice(device: ALCdevice): bool {.cdecl, importc.}

proc alcGetError

proc alcGetError(device: ALCdevice): ALCenum {.cdecl, importc.}

proc alcIsExtensionPresent

proc alcIsExtensionPresent(device: ALCdevice; extname: ptr ALCchar): bool {.cdecl, importc.}

proc alcGetProcAddress

proc alcGetProcAddress(device: ALCdevice; funcname: ptr ALCchar): pointer {.cdecl, importc.}

proc alcGetEnumValue

proc alcGetEnumValue(device: ALCdevice; enumname: ptr ALCchar): ALCenum {.cdecl, importc.}

proc alcGetString

proc alcGetString(device: ALCdevice; param: ALCenum): ptr ALCchar {.cdecl, importc.}

proc alcGetIntegerv

proc alcGetIntegerv(device: ALCdevice; param: ALCenum; size: ALCsizei; data: ptr ALCint) {.cdecl, importc.}

proc alcCaptureOpenDevice

proc alcCaptureOpenDevice(devicename: ptr ALCchar; frequency: ALCuint;
                         format: ALCenum; buffersize: ALCsizei): ALCdevice {.cdecl, importc.}

proc alcCaptureCloseDevice

proc alcCaptureCloseDevice(device: ALCdevice): bool {.cdecl, importc.}

proc alcCaptureStart

proc alcCaptureStart(device: ALCdevice) {.cdecl, importc.}

proc alcCaptureStop

proc alcCaptureStop(device: ALCdevice) {.cdecl, importc.}

proc alcCaptureSamples

proc alcCaptureSamples(device: ALCdevice; buffer: pointer; samples: ALCsizei) {.cdecl, importc.}

openal's Issues

Static linking for windows users

Windows, like linux and macos supports static linking.
The way the program is linked should not depend on the OS but on a -d flag.

A -d:openalStatic flag could be used to mean to link openal statically..
I could not find any standard way to inform the Nim program how to link the dependencies hence the name openalStatic (freetype already does that.)

when defined(openalStatic)
  when defined(macosx) or defined(ios):
    {.passL: "-framework OpenAL".}
  else:
    {.passL: "-lopenal"}
  {.push importc.}
else:
  when defined(windows):
    {.push cdecl, dynlib: "soft_oal.dll", importc.}
  elif defined(linux):
    {.push cdecl, dynlib: "<the correct shared library name>.so", importc.}
  elif defined(macosx):
    {.push cdecl, dynlib: "<the correct shared library name>.dynlib", importc.}
  else:
     {.error: "This platform does not support dynamic linking".}

Why const AL_NO_ERROR* = false?

AL_NO_ERROR is defined as const AL_NO_ERROR* = false in src/openal.nim.
But it is defined #define AL_NO_ERROR 0 in al.h.
As type of the return value of alGetError() is ALenum, I have to cast it to compare to AL_NO_ERROR.
Can you change it to AL_NO_ERROR* = 0?