al

package
v0.0.0-...-a69e9a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2014 License: BSD-2-Clause Imports: 2 Imported by: 0

Documentation

Overview

Go binding for OpenAL's "al" API.

See http://connect.creativelabs.com/openal/Documentation/OpenAL%201.1%20Specification.htm for details about OpenAL not described here.

OpenAL types are (in principle) mapped to Go types as follows: 

ALboolean	bool	(al.h says char, but Go's bool should be compatible)
ALchar		uint8	(although al.h suggests int8, Go's uint8 (aka byte) seems better)
ALbyte		int8	(al.h says char, implying that char is signed)
ALubyte		uint8	(al.h says unsigned char)
ALshort		int16
ALushort	uint16
ALint		int32
ALuint		uint32
ALsizei		int32	(although that's strange, it's what OpenAL wants)
ALenum		int32	(although that's strange, it's what OpenAL wants)
ALfloat		float32
ALdouble	float64
ALvoid		not applicable (but see below)

We also stick to these (not mentioned explicitly in OpenAL): 

ALvoid*		unsafe.Pointer (but never exported)
ALchar*		string

Finally, in places where OpenAL expects pointers to C-style arrays, we use Go slices if appropriate: 

ALboolean*	[]bool
ALvoid*		[]byte (see Buffer.SetData() for example)
ALint*		[]int32
ALuint*		[]uint32 []Source []Buffer
ALfloat*	[]float32
ALdouble*	[]float64

Overall, the correspondence of types hopefully feels natural enough. Note that many of these types do not actually occur in the API.

The names of OpenAL constants follow the established Go conventions: instead of AL_FORMAT_MONO16 we use FormatMono16 for example.

Conversion to Go's camel case notation does however lead to name clashes between constants and functions. For example, AL_DISTANCE_MODEL becomes DistanceModel which collides with the OpenAL function of the same name used to set the current distance model. We have to rename either the constant or the function, and since the function name seems to be at fault (it's a setter but doesn't make that obvious), we rename the function.

In fact, we renamed plenty of functions, not just the ones where collisions with constants were the driving force. For example, instead of the Sourcef/GetSourcef abomination, we use Getf/Setf methods on a Source type. Everything should still be easily recognizable for OpenAL hackers, but this structure is a lot more sensible (and reveals that the OpenAL API is actually not such a bad design).

There are a few cases where constants would collide with the names of types we introduced here. Since the types serve a much more important function, we renamed the constants in those cases. For example AL_BUFFER would collide with the type Buffer so it's name is now Buffer_ instead. Not pretty, but in many cases you don't need the constants anyway as the functionality they represent is probably available through one of the convenience functions we introduced as well. For example consider the task of attaching a buffer to a source. In C, you'd say alSourcei(sid, AL_BUFFER, bid). In Go, you can say sid.Seti(Buffer_, bid) as well, but you probably want to say sid.SetBuffer(bid) instead.

TODO: Decide on the final API design; the current state has only specialized methods, none of the generic ones anymore; it exposes everything (except stuff we can't do) but I am not sure whether this is the right API for the level we operate on. Not yet anyway. Anyone?

Index

Constants

View Source 
const (
	FormatMono8    = 0x1100
	FormatMono16   = 0x1101
	FormatStereo8  = 0x1102
	FormatStereo16 = 0x1103
)

Format of sound samples passed to Buffer.SetData().

View Source 
const (
	NoError          = alFalse
	InvalidName      = 0xA001
	InvalidEnum      = 0xA002
	InvalidValue     = 0xA003
	InvalidOperation = 0xA004
)

Error codes from GetError()/for GetString().

View Source 
const (
	InverseDistance         = 0xD001
	InverseDistanceClamped  = 0xD002
	LinearDistance          = 0xD003
	LinearDistanceClamped   = 0xD004
	ExponentDistance        = 0xD005
	ExponentDistanceClamped = 0xD006
)

Distance models for SetDistanceModel() and GetDistanceModel().

View Source 
const (
	Initial = 0x1011
	Playing = 0x1012
	Paused  = 0x1013
	Stopped = 0x1014
)

Results from Source.State() query.

View Source 
const (
	Static       = 0x1028
	Streaming    = 0x1029
	Undetermined = 0x1030
)

Results from Source.Type() query.

View Source 
const (
	None = 0
)

General purpose constants. None can be used with SetDistanceModel() to disable distance attenuation. None can be used with Source.SetBuffer() to clear a Source of buffers.

Variables

This section is empty.

Functions

func DeleteBuffer 

func DeleteBuffer(buffer Buffer)

DeleteBuffer() deletes a single buffer. Convenience function, see DeleteBuffers().

func DeleteBuffers 

func DeleteBuffers(buffers []Buffer)

DeleteBuffers() deletes the given buffers.

func DeleteSource 

func DeleteSource(source Source)

DeleteSource() deletes a single source. Convenience function, see DeleteSources().

func DeleteSources 

func DeleteSources(sources []Source)

DeleteSources() deletes the given sources.

func GetDistanceModel 

func GetDistanceModel() int32

Convenience function, see GetInteger().

func GetDopplerFactor 

func GetDopplerFactor() float32

Convenience function, see GetFloat().

func GetDopplerVelocity 

func GetDopplerVelocity() float32

Convenience function, see GetFloat().

func GetError 

func GetError() uint32

GetError() returns the most recent error generated in the AL state machine.

func GetExtensions 

func GetExtensions() string

Convenience function, see GetString().

func GetRenderer 

func GetRenderer() string

Convenience function, see GetString().

func GetSpeedOfSound 

func GetSpeedOfSound() float32

Convenience function, see GetFloat().

func GetString 

func GetString(param int32) string

func GetVendor 

func GetVendor() string

Convenience function, see GetString().

func GetVersion 

func GetVersion() string

Convenience function, see GetString().

func PauseSources 

func PauseSources(sources []Source)

Renamed, was SourcePausev.

func PlaySources 

func PlaySources(sources []Source)

Renamed, was SourcePlayv.

func RewindSources 

func RewindSources(sources []Source)

Renamed, was SourceRewindv.

func SetDistanceModel 

func SetDistanceModel(model int32)

SetDistanceModel() changes the current distance model. Pass "None" to disable distance attenuation. Renamed, was DistanceModel.

func SetDopplerFactor 

func SetDopplerFactor(value float32)

Renamed, was DopplerFactor.

func SetDopplerVelocity 

func SetDopplerVelocity(value float32)

Renamed, was DopplerVelocity.

func SetSpeedOfSound 

func SetSpeedOfSound(value float32)

Renamed, was SpeedOfSound.

func StopSources 

func StopSources(sources []Source)

Renamed, was SourceStopv.

Types

type Buffer 

type Buffer uint32

Buffers are storage space for sample data.

func NewBuffer 

func NewBuffer() Buffer

NewBuffer() creates a single buffer. Convenience function, see NewBuffers().

func NewBuffers 

func NewBuffers(n int) (buffers []Buffer)

NewBuffers() creates n fresh buffers. Renamed, was GenBuffers.

func (Buffer) GetBits 

func (self Buffer) GetBits() uint32

GetBits() returns the resolution, either 8 or 16 bits, of the buffer's sample data. Convenience method.

func (Buffer) GetChannels 

func (self Buffer) GetChannels() uint32

GetChannels() returns the number of channels, either 1 or 2, of the buffer's sample data. Convenience method.

func (Buffer) GetFrequency 

func (self Buffer) GetFrequency() uint32

GetFrequency() returns the frequency, in Hz, of the buffer's sample data. Convenience method.

func (Buffer) GetSize 

func (self Buffer) GetSize() uint32

GetSize() returns the size, in bytes, of the buffer's sample data. Convenience method.

func (Buffer) SetData 

func (self Buffer) SetData(format int32, data []byte, frequency int32)

SetData() specifies the sample data the buffer should use. For FormatMono16 and FormatStereo8 the data slice must be a multiple of two bytes long; for FormatStereo16 the data slice must be a multiple of four bytes long. The frequency is given in Hz. Renamed, was BufferData.

type Listener 

type Listener struct{}

Listener represents the singleton receiver of sound in 3d space.

We "fake" this type so we can provide OpenAL listener calls as methods. This is convenient and makes all those calls consistent with the way they work for Source and Buffer. You can't make new listeners, there's only one!

func (Listener) GetGain 

func (self Listener) GetGain() (gain float32)

Convenience method, see Listener.Getf().

func (Listener) GetOrientation 

func (self Listener) GetOrientation() (at Vector, up Vector)

TODO: is there a better way to do this? Convenience method, see Listener.Getfv().

func (Listener) GetPosition 

func (self Listener) GetPosition() Vector

Convenience method, see Listener.Getfv().

func (Listener) GetVelocity 

func (self Listener) GetVelocity() Vector

Convenience method, see Listener.Getfv().

func (Listener) SetGain 

func (self Listener) SetGain(gain float32)

Convenience method, see Listener.Setf().

func (Listener) SetOrientation 

func (self Listener) SetOrientation(at Vector, up Vector)

TODO: is there a better way to do this? Convenience method, see Listener.Setfv().

func (Listener) SetPosition 

func (self Listener) SetPosition(vector Vector)

Convenience method, see Listener.Setfv().

func (Listener) SetVelocity 

func (self Listener) SetVelocity(vector Vector)

Convenience method, see Listener.Setfv().

type Source 

type Source uint32

Sources represent sound emitters in 3d space.

func NewSource 

func NewSource() Source

NewSource() creates a single source. Convenience function, see NewSources().

func NewSources 

func NewSources(n int) (sources []Source)

NewSources() creates n sources. Renamed, was GenSources.

func (Source) BuffersProcessed 

func (self Source) BuffersProcessed() int32

Convenience method, see Source.Geti().

func (Source) BuffersQueued 

func (self Source) BuffersQueued() int32

Convenience method, see Source.Geti().

func (Source) GetBuffer 

func (self Source) GetBuffer() (buffer Buffer)

Convenience method, see Source.Geti().

func (Source) GetDirection 

func (self Source) GetDirection() Vector

Convenience method, see Source.Getfv().

func (Source) GetGain 

func (self Source) GetGain() (gain float32)

Convenience method, see Source.Getf().

func (Source) GetInnerAngle 

func (self Source) GetInnerAngle() float32

Convenience method, see Source.Getf().

func (Source) GetLooping 

func (self Source) GetLooping() bool

Convenience method, see Source.Geti().

func (Source) GetMaxDistance 

func (self Source) GetMaxDistance() (distance float32)

Convenience method, see Source.Getf().

func (Source) GetMaxGain 

func (self Source) GetMaxGain() (gain float32)

Convenience method, see Source.Getf().

func (Source) GetMinGain 

func (self Source) GetMinGain() (gain float32)

Convenience method, see Source.Getf().

func (Source) GetOffsetBytes 

func (self Source) GetOffsetBytes() int32

Convenience method, see Source.Geti().

func (Source) GetOffsetSamples 

func (self Source) GetOffsetSamples() int32

Convenience method, see Source.Geti().

func (Source) GetOffsetSeconds 

func (self Source) GetOffsetSeconds() float32

Convenience method, see Source.Getf().

func (Source) GetOuterAngle 

func (self Source) GetOuterAngle() float32

Convenience method, see Source.Getf().

func (Source) GetOuterGain 

func (self Source) GetOuterGain() float32

Convenience method, see Source.Getf().

func (Source) GetPitch 

func (self Source) GetPitch() (gain float32)

Convenience method, see Source.Getf().

func (Source) GetPosition 

func (self Source) GetPosition() Vector

Convenience method, see Source.Getfv().

func (Source) GetReferenceDistance 

func (self Source) GetReferenceDistance() (distance float32)

Convenience method, see Source.Getf().

func (Source) GetRolloffFactor 

func (self Source) GetRolloffFactor() (gain float32)

Convenience method, see Source.Getf().

func (Source) GetSourceRelative 

func (self Source) GetSourceRelative() bool

Convenience method, see Source.Geti().

func (Source) GetVelocity 

func (self Source) GetVelocity() Vector

Convenience method, see Source.Getfv().

func (Source) Pause 

func (self Source) Pause()

Renamed, was SourcePause.

func (Source) Play 

func (self Source) Play()

Renamed, was SourcePlay.

func (Source) QueueBuffer 

func (self Source) QueueBuffer(buffer Buffer)

Convenience method, see Source.QueueBuffers().

func (Source) QueueBuffers 

func (self Source) QueueBuffers(buffers []Buffer)

Renamed, was SourceQueueBuffers.

func (Source) Rewind 

func (self Source) Rewind()

Renamed, was SourceRewind.

func (Source) SetBuffer 

func (self Source) SetBuffer(buffer Buffer)

Convenience method, see Source.Geti().

func (Source) SetDirection 

func (self Source) SetDirection(vector Vector)

Convenience method, see Source.Setfv().

func (Source) SetGain 

func (self Source) SetGain(gain float32)

Convenience method, see Source.Setf().

func (Source) SetInnerAngle 

func (self Source) SetInnerAngle(offset float32)

Convenience method, see Source.Setf().

func (Source) SetLooping 

func (self Source) SetLooping(yes bool)

Convenience method, see Source.Seti().

func (Source) SetMaxDistance 

func (self Source) SetMaxDistance(distance float32)

Convenience method, see Source.Setf().

func (Source) SetMaxGain 

func (self Source) SetMaxGain(gain float32)

Convenience method, see Source.Setf().

func (Source) SetMinGain 

func (self Source) SetMinGain(gain float32)

Convenience method, see Source.Setf().

func (Source) SetOffsetBytes 

func (self Source) SetOffsetBytes(offset int32)

Convenience method, see Source.Seti().

func (Source) SetOffsetSamples 

func (self Source) SetOffsetSamples(offset int32)

Convenience method, see Source.Seti().

func (Source) SetOffsetSeconds 

func (self Source) SetOffsetSeconds(offset float32)

Convenience method, see Source.Setf().

func (Source) SetOuterAngle 

func (self Source) SetOuterAngle(offset float32)

Convenience method, see Source.Setf().

func (Source) SetOuterGain 

func (self Source) SetOuterGain(offset float32)

Convenience method, see Source.Setf().

func (Source) SetPitch 

func (self Source) SetPitch(gain float32)

Convenience method, see Source.Setf().

func (Source) SetPosition 

func (self Source) SetPosition(vector Vector)

Convenience method, see Source.Setfv().

func (Source) SetReferenceDistance 

func (self Source) SetReferenceDistance(distance float32)

Convenience method, see Source.Setf().

func (Source) SetRolloffFactor 

func (self Source) SetRolloffFactor(gain float32)

Convenience method, see Source.Setf().

func (Source) SetSourceRelative 

func (self Source) SetSourceRelative(yes bool)

Convenience method, see Source.Seti().

func (Source) SetVelocity 

func (self Source) SetVelocity(vector Vector)

Convenience method, see Source.Setfv().

func (Source) State 

func (self Source) State() int32

Convenience method, see Source.Geti().

func (Source) Stop 

func (self Source) Stop()

Renamed, was SourceStop.

func (Source) Type 

func (self Source) Type() int32

Convenience method, see Source.Geti().

func (Source) UnqueueBuffer 

func (self Source) UnqueueBuffer() Buffer

Convenience method, see Source.QueueBuffers().

func (Source) UnqueueBuffers 

func (self Source) UnqueueBuffers(buffers []Buffer)

Renamed, was SourceUnqueueBuffers.

type Vector 

type Vector [3]float32

Convenience type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.