1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
% Psychtoolbox:PsychSound -- Psychtoolbox sound functions, based on OpenAL
% and PsychPortAudio.
%
% If you need "traditional" support for audio capture or output as most do,
% see "help PsychPortAudio" and "help InitializePsychSound" for info about
% our excellent PsychPortAudio driver.
%
% If you need 3D spatialized sound output, read on!
%
% Psychtoolbox allows you to directly call low-level OpenAL commands from
% the Matlab environment in nearly the same way as you could do from native
% C or C++ code. This way you can code and use sound recording
% algorithms and 3D sound output algorithms in Matlab, utilizing the power of
% modern sound hardware by calling OpenAL functions.
%
% Access to OpenAL from Matlab is provided by the "Matlab OpenAL toolbox"
% (MOAL) which was derived from the MOGL toolbox for OpenGL.
%
% OpenAL is a free (free software), cross-platform (Windows, Macintosh, Linux),
% highly efficient, easy to learn, flexible audio library which incorporates
% advanced features like 3D spatialized sound, multi-channel support, streaming,
% audio capture, special effects like echo, reverb, attenuation, doppler effects
% and other stuff. Its programming model and API closely resembles OpenGL, so
% OpenGL programmers will find themselves immediatels at home with this library,
% and its very easy to extend 3D graphics code with corresponding 3D sound.
%
% MOAL provides one Matlab wrapper M-File for each corresponding OpenAL
% function. The wrapper file calls into a special MEX file (moalcore) which
% implements the C-language interface to OpenAL. The syntax of a Matlab
% OpenAL command is mostly identical to its C counterpart with a few
% small exceptions that are imposed to us by the design of Matlab:
%
% 1. Return values are returned in Matlab-style, as left-hand side
% arguments of the calls, instead of being right-hand side arguments as in
% C:
%
% E.g., the C language call alGetIntegerv(GLenum pname, GLint* params);
% becomes params = alGetIntegerv(pname); in Matlab, because 'params' is a
% return argument of alGetIntegerv.
%
% 2. Commands that don't take arguments don't have empty braces, because
% Matlab doesn't allow this:
%
% E.g., the C language call alEnd(); becomes alEnd; in Matlab.
%
% 3. All AL, ALU and ALC constants start with prefix AL. instead of AL_
% E.g., AL_TRUE becomes AL.TRUE ...
%
% Each subroutine that intends to use AL constants needs to define the
% variable AL as global: Example
% function myOpenALSubroutine()
% global AL; % Define AL variable as global.
% ...rest of function implementation...
% return;
%
% If you want to use ALC constants, then 'global ALC' is also needed.
%
% 4. In your main Matlab script or M-File you need to call the function
% InitializeMatlabOpenAL; This command initializes the OpenAL for Matlab toolbox and
% sets up Psychtoolbox to play nicely with Matlab-OpenAL and other OpenAL
% toolboxes.
%
%
% Support for 3rd party OpenAL MEX-Files:
%
% You can also code up OpenAL algorithms in the C programming language and
% compile them into Matlab-MEX files if you have "need for speed". Your Mex
% files will just contain the mixture of ANSI C code and OpenAL calls, but
% no code to setup the OpenAL rendering context. You just need to call the
% InitializeMatlabOpenAL; function. After that call, an audio device will
% be set up and the associated OpenAL rendering context will be active. All
% commands in your MEX-File will apply to that rendering context.
%
% If you want to write OpenAL mex-files that are portable across different
% operating systems (OS-X, Windows, Linux) then have a look at:
% 'Psychtoolbox/PsychSound/MOAL/source' for how to do this. This folder
% contains the source code and Makefiles for our own moalcore mex-file...
%
% KNOWN LIMITATIONS:
%
% Depending on your specific code, rendering speed in Matlab may be
% slightly lower than when executing the same code from C or C++. This
% is the price you'll have to pay for using Matlab, but our abstraction
% layer is very thin, so most applications won't be really affected.
%
% Some OpenAL extension functions are not yet implemented in the toolbox, because
% these functions can't get automatically generated, so their wrappers need
% to be coded manually. Our goal is to provide sufficient support for the
% OpenAL-API, but finalizing all functions may take some time.
%
% Apart from these limitations that will get removed in the future, there
% are limitations imposed by your operating system and sound hardware.
%
% Support for OpenAL functions varies between different sound hardware,
% so if you want to use the latest and greatest OpenAL functions, you'll
% need to buy and install the latest and greatest sound hardware.
%
% Typical limitations of low-end versus high-end hardware:
% - Number of sound sources / channels that can be played back simultaneously.
% - Complexity of audio processing that can be performed.
% - Latency in sound processing.
% - Quality of 3D spatial audio rendering.
%
% CONTENTS:
%
% * All supported OpenAL low-level functions can be found in the folder
% 'Psychtoolbox/PsychSound/MOAL/wrap/'. Functions prefixed with _ are not
% yet implemented.
%
% * High-level helper functions can be found in 'Psychtoolbox/PsychSound/'
% and its subfolders.
%
% * Demos can be found in 'Psychtoolbox/PsychDemos/SoundDemos'
%
% Lot's of documentation, tutorials, code samples and news about OpenAL can
% be found by following links at:
%
% http://www.openal.org
%
% A FOSS open-source software implementation of OpenAL, which is typically used
% on GNU/Linux, and which has many advanced features implemented as extensions,
% e.g., pretty flexible HRTF based sound rendering, can be found at:
%
% https://openal-soft.org
%
% Googling for OpenAL is also a option.
%
% Enjoy!
% History:
% 7.02.2007 -- created (MK)
% 15.7.2019 -- updated (MK)
|
