gh0s7/Lucina3DS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First Commit

Browse Source
This commit is contained in:
CGH0S7
2025-02-06 22:24:29 +08:00
parent ed7df4c81e
commit 7539e6a53c
18116 changed files with 6181499 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
externals/openal-soft/docs/3D7.1.txt vendored Normal file
View File

@@ -0,0 +1,75 @@
Overview
========
3D7.1 is a custom speaker layout designed by Simon Goodwin at Codemasters[1].
Typical surround sound setups, like quad, 5.1, 6.1, and 7.1, only produce audio
on a 2D horizontal plane with no verticality, which means the envelopment of
"surround" sound is limited to left, right, front, and back panning. Sounds
that should come from above or below will still only play in 2D since there is
no height difference in the speaker array.
To work around this, 3D7.1 was designed so that some speakers are placed higher
than the listener while others are lower, in a particular configuration that
tries to provide balanced output and maintain some compatibility with existing
audio content and software. Software that recognizes this setup, or can be
configured for it, can then take advantage of the height difference and
increase the perception of verticality for true 3D audio. The result is that
sounds can be perceived as coming from left, right, front, and back, as well as
up and down.
[1] http://www.codemasters.com/research/3D_sound_for_3D_games.pdf
Hardware Setup
==============
Setting up 3D7.1 requires an audio device capable of raw 8-channel or 7.1
output, along with a 7.1 speaker kit. The speakers should be hooked up to the
device in the usual way, with front-left and front-right output going to the
front-left and front-right speakers, etc. The placement of the speakers should
be set up according to the table below. Azimuth is the horizontal angle in
degrees, with 0 directly in front and positive values go /left/, and elevation
is the vertical angle in degrees, with 0 at head level and positive values go
/up/.
------------------------------------------------------------
- Speaker label | Azimuth | Elevation | New label -
------------------------------------------------------------
- Front left | 51 | 24 | Upper front left -
- Front right | -51 | 24 | Upper front right -
- Front center | 0 | 0 | Front center -
- Subwoofer/LFE | N/A | N/A | Subwoofer/LFE -
- Side left | 129 | -24 | Lower back left -
- Side right | -129 | -24 | Lower back right -
- Back left | 180 | 55 | Upper back center -
- Back right | 0 | -55 | Lower front center -
------------------------------------------------------------
Note that this speaker layout *IS NOT* compatible with standard 7.1 content.
Audio that should be played from the back will come out at the wrong location
since the back speakers are placed in the lower front and upper back positions.
However, this speaker layout *IS* more or less compatible with standard 5.1
content. Though slightly tilted, to a listener sitting a bit further back from
the center, the front and side speakers will be close enough to their intended
locations that the output won't be too off.
Software Setup
==============
To enable 3D7.1 on OpenAL Soft, first make sure the audio device is configured
for 7.1 output. Then in the alsoft-config utility, for the Channels setting
choose "3D7.1 Surround" from the drop-down list. And that's it. Any application
using OpenAL Soft can take advantage of fully 3D audio, and multi-channel
sounds will be properly remixed for the speaker layout.
Note that care must be taken that the audio device is not treated as a "true"
7.1 device by non-3D7.1-capable applications. In particular, the audio server
should not try to upmix stereo and 5.1 content to "fill out" the back speakers,
and non-3D7.1 apps should be set to either stereo or 5.1 output.
As such, if your system is capable of it, it may be useful to define a virtual
5.1 device that maps the front, side, and LFE channels to the main device for
output and disables upmixing, then use that virtual 5.1 device for apps that do
normal stereo or surround sound output, and use the main device for apps that
understand 3D7.1 output.

192
externals/openal-soft/docs/ambdec.txt vendored Normal file
View File

@@ -0,0 +1,192 @@
AmbDec Configuration Files
==========================
AmbDec configuration files were developed by Fons Adriaensen as part of the
AmbDec program <http://kokkinizita.linuxaudio.org/linuxaudio/index.html>.
The file works by specifying a decoder matrix or matrices which transform
ambisonic channels into speaker feeds. Single-band decoders specify a single
matrix that transforms all frequencies, while dual-band decoders specifies two
matrices where one transforms low frequency sounds and the other transforms
high frequency sounds. See docs/ambisonics.txt for more general information
about ambisonics.
Starting with OpenAL Soft 1.18, version 3 of the file format is supported as a
means of specifying custom surround sound speaker layouts. These configuration
files are also used to enable per-speaker distance compensation.
File Format
===========
As of this writing, there is no official documentation of the .ambdec file
format. However, the format as OpenAL Soft sees it is as follows:
The file is plain text. Comments start with a hash/pound character (#). There
may be any amount of whitespace in between the option and parameter values.
Strings are *not* enclosed in quotation marks.
/description <desc:string>
Specifies a text description of the configuration. Ignored by OpenAL Soft.
/version <ver:int>
Declares the format version used by the configuration file. OpenAL Soft
currently only supports version 3.
/dec/chan_mask <mask:hex>
Specifies a hexadecimal mask value of ambisonic input channels used by this
decoder. Counting up from the least significant bit, bit 0 maps to Ambisonic
Channel Number (ACN) 0, bit 1 maps to ACN 1, etc. As an example, a value of 'b'
enables bits 0, 1, and 3 (1011 in binary), which correspond to ACN 0, 1, and 3
(first-order horizontal).
/dec/freq_bands <count:int>
Specifies the number of frequency bands used by the decoder. This must be 1 for
single-band or 2 for dual-band.
/dec/speakers <count:int>
Specifies the number of output speakers to decode to.
/dec/coeff_scale <type:string>
Specifies the scaling used by the decoder coefficients. Currently recognized
types are fuma, sn3d, and n3d, for Furse-Malham (FuMa), semi-normalized (SN3D),
and fully normalized (N3D) scaling, respectively.
/opt/input_scale <name:string>
Specifies the scaling used by the ambisonic input data. As OpenAL Soft renders
the data itself and knows the scaling, this is ignored.
/opt/nfeff_comp <dir:string>
Specifies whether near-field effect compensation is off (not applied at all),
applied on input (faster, less accurate with varying speaker distances) or
output (slower, more accurate with varying speaker distances). Ignored by
OpenAL Soft.
/opt/delay_comp <onoff:bool>
Specifies whether delay compensation is applied for output. This is used to
correct for time variations caused by different speaker distances. As OpenAL
Soft has its own config option for this, this is ignored.
/opt/level_comp <onoff:bool>
Specifies whether gain compensation is applied for output. This is used to
correct for volume variations caused by different speaker distances. As OpenAL
Soft has its own config option for this, this is ignored.
/opt/xover_freq <freq:float>
Specifies the crossover frequency for dual-band decoders. Frequencies less than
this are fed to the low-frequency matrix, and frequencies greater than this are
fed to the high-frequency matrix. Unused for single-band decoders.
/opt/xover_ratio <decibels:float>
Specifies the volume ratio between the frequency bands. Values greater than 0
decrease the low-frequency output by half the specified value and increase the
high-frequency output by half the specified value, while values less than 0
increase the low-frequency output and decrease the high-frequency output to
similar effect. Unused for single-band decoders.
/speakers/{
Begins the output speaker definitions. A speaker is defined using the add_spkr
command, and there must be a matching number of speaker definitions as the
specified speaker count. The definitions are ended with a "/}".
add_spkr <id:string> <dist:float> <azi:float> <elev:float> <connection:string>
Defines an output speaker. The ID is a string identifier for the output speaker
(see Speaker IDs below). The distance is in meters from the center-point of the
physical speaker array. The azimuth is the horizontal angle of the speaker, in
degrees, where 0 is directly front and positive values go left. The elevation
is the vertical angle of the speaker, in degrees, where 0 is directly front and
positive goes upward. The connection string is the JACK port name the speaker
should connect to. Currently, OpenAL Soft uses the ID and distance, and ignores
the rest.
/lfmatrix/{
Begins the low-frequency decoder matrix definition. The definition should
include an order_gain command to specify the base gain for the ambisonic
orders. Each matrix row is defined using the add_row command, and there must be
a matching number of rows as the number of speakers. Additionally the row
definitions are in the same order as the speaker definitions. The definitions
are ended with a "/}". Only valid for dual-band decoders.
/hfmatrix/{
Begins the high-frequency decoder matrix definition. The definition should
include an order_gain command to specify the base gain for the ambisonic
orders. Each matrix row is defined using the add_row command, and there must be
a matching number of rows as the number of speakers, Additionally the row
definitions are in the same order as the speaker definitions. The definitions
are ended with a "/}". Only valid for dual-band decoders.
/matrix/{
Begins the decoder matrix definition. The definition should include an
order_gain command to specify the base gain for the ambisonic orders. Each
matrix row is defined using the add_row command, and there must be a matching
number of rows as the number of speakers. Additionally the row definitions are
in the same order as the speaker definitions. The definitions are ended with a
"/}". Only valid for single-band decoders.
order_gain <gain:float> <gain:float> <gain:float> <gain:float>
Specifies the base gain for the zeroth-, first-, second-, and third-order
coefficients in the given matrix, automatically scaling the related
coefficients. This should be specified at the beginning of the matrix
definition.
add_row <coefficient:float> ...
Specifies a row of coefficients for the matrix. There should be one coefficient
for each enabled bit in the channel mask, and corresponds to the matching ACN
channel.
/end
Marks the end of the configuration file.
Speaker IDs
===========
The AmbDec program uses the speaker ID as a label to display in its config
dialog, but does not otherwise use it for any particular purpose. However,
since OpenAL Soft needs to match a speaker definition to an output channel, the
speaker ID is used to identify what output channel it correspond to. Therefore,
OpenAL Soft requires these channel labels to be recognized:
LF = Front left
RF = Front right
LS = Side left
RS = Side right
LB = Back left
RB = Back right
CE = Front center
CB = Back center
LFT = Top front left
RFT = Top front right
LBT = Top back left
RBT = Top back right
Additionally, configuration files for surround51 will acknowledge back speakers
for side channels, to avoid issues with a configuration expecting 5.1 to use
the side channels when the device is configured for back, or vice-versa.
Furthermore, OpenAL Soft does not require a speaker definition for each output
channel the configuration is used with. So for example a 5.1 configuration may
omit a front center speaker definition, in which case the front center output
channel will not contribute to the ambisonic decode (though OpenAL Soft will
still use it in certain scenarios, such as the AL_EFFECT_DEDICATED_DIALOGUE
effect).
Creating Configuration Files
============================
Configuration files can be created or modified by hand in a text editor. The
AmbDec program also has a GUI for creating and editing them. However, these
methods rely on you having the coefficients to fill in... they won't be
generated for you.
Another option is to use the Ambisonic Decoder Toolbox
<https://bitbucket.org/ambidecodertoolbox/adt.git>. This is a collection of
MATLAB and GNU Octave scripts that can generate AmbDec configuration files from
an array of speaker definitions (labels and positions). If you're familiar with
using MATLAB or GNU Octave, this may be a good option.
There are plans for OpenAL Soft to include a utility to generate coefficients
and make configuration files. However, calculating proper coefficients for
anything other than regular or semi-regular speaker setups is somewhat of a
black art, so may take some time.

112
externals/openal-soft/docs/ambisonics.txt vendored Normal file
View File

@@ -0,0 +1,112 @@
OpenAL Soft's renderer has advanced quite a bit since its start with panned
stereo output. Among these advancements is support for surround sound output,
using psychoacoustic modeling and more accurate plane wave reconstruction. The
concepts in use may not be immediately obvious to people just getting into 3D
audio, or people who only have more indirect experience through the use of 3D
audio APIs, so this document aims to introduce the ideas and purpose of
Ambisonics as used by OpenAL Soft.
What Is It?
===========
Originally developed in the 1970s by Michael Gerzon and a team others,
Ambisonics was created as a means of recording and playing back 3D sound.
Taking advantage of the way sound waves propogate, it is possible to record a
fully 3D soundfield using as few as 4 channels (or even just 3, if you don't
mind dropping down to 2 dimensions like many surround sound systems are). This
representation is called B-Format. It was designed to handle audio independent
of any specific speaker layout, so with a proper decoder the same recording can
be played back on a variety of speaker setups, from quadraphonic and hexagonal
to cubic and other periphonic (with height) layouts.
Although it was developed decades ago, various factors held ambisonics back
from really taking hold in the consumer market. However, given the solid
theories backing it, as well as the potential and practical benefits on offer,
it continued to be a topic of research over the years, with improvements being
made over the original design. One of the improvements made is the use of
Spherical Harmonics to increase the number of channels for greater spatial
definition. Where the original 4-channel design is termed as "First-Order
Ambisonics", or FOA, the increased channel count through the use of Spherical
Harmonics is termed as "Higher-Order Ambisonics", or HOA. The details of higher
order ambisonics are out of the scope of this document, but know that the added
channels are still independent of any speaker layout, and aim to further
improve the spatial detail for playback.
Today, the processing power available on even low-end computers means real-time
Ambisonics processing is possible. Not only can decoders be implemented in
software, but so can encoders, synthesizing a soundfield using multiple panned
sources, thus taking advantage of what ambisonics offers in a virtual audio
environment.
How Does It Help?
=================
Positional sound has come a long way from pan-pot stereo (aka pair-wise).
Although useful at the time, the issues became readily apparent when trying to
extend it for surround sound. Pan-pot doesn't work as well for depth (front-
back) or vertical panning, it has a rather small "sweet spot" (the area the
head needs to be in to perceive the sound in its intended direction), and it
misses key distance-related details of sound waves.
Ambisonics takes a different approach. It uses all available speakers to help
localize a sound, and it also takes into account how the brain localizes low
frequency sounds compared to high frequency ones -- a so-called psychoacoustic
model. It may seem counter-intuitive (if a sound is coming from the front-left,
surely just play it on the front-left speaker?), but to properly model a sound
coming from where a speaker doesn't exist, more needs to be done to construct a
proper sound wave that's perceived to come from the intended direction. Doing
this creates a larger sweet spot, allowing the perceived sound direction to
remain correct over a larger area around the center of the speakers.
In addition, Ambisonics can encode the near-field effect of sounds, effectively
capturing the sound distance. The near-field effect is a subtle low-frequency
boost as a result of wave-front curvature, and properly compensating for this
occuring with the output speakers (as well as emulating it with a synthesized
soundfield) can create an improved sense of distance for sounds that move near
or far.
How Is It Used?
===============
As a 3D audio API, OpenAL is tasked with playing 3D sound as best it can with
the speaker setup the user has. Since the OpenAL API doesn't expose discrete
playback speaker feeds, an implementation has a lot of leeway with how to deal
with the audio before it's played back for the user to hear. Consequently,
OpenAL Soft (or any other OpenAL implementation that wishes to) can render
using Ambisonics and decode the ambisonic mix for a high level of accuracy over
what simple pan-pot could provide.
In addition to surround sound output, Ambisonics also has benefits with stereo
output. 2-channel UHJ is a stereo-compatible format that encodes some surround
sound information using a wide-band 90-degree phase shift filter. This is
generated by taking the ambisonic mix and deriving a front-stereo mix with
with the rear sounds filtered in with it. Although the result is not as good as
3-channel (2D) B-Format, it has the distinct advantage of only using 2 channels
and being compatible with stereo output. This means it will sound just fine
when played as-is through a normal stereo device, or it may optionally be fed
to a properly configured surround sound receiver which can extract the encoded
information and restore some of the original surround sound signal.
What Are Its Limitations?
=========================
As good as Ambisonics is, it's not a magic bullet that can overcome all
problems. One of the bigger issues it has is dealing with irregular speaker
setups, such as 5.1 surround sound. The problem mainly lies in the imbalanced
speaker positioning -- there are three speakers within the front 60-degree area
(meaning only 30-degree gaps in between each of the three speakers), while only
two speakers cover the back 140-degree area, leaving 80-degree gaps on the
sides. It should be noted that this problem is inherent to the speaker layout
itself; there isn't much that can be done to get an optimal surround sound
response, with ambisonics or not. It will do the best it can, but there are
trade-offs between detail and accuracy.
Another issue lies with HRTF. While it's certainly possible to play an
ambisonic mix using HRTF and retain a sense of 3D sound, doing so with a high
degree of spatial detail requires a fair amount of resources, in both memory
and processing time. And even with it, mixing sounds with HRTF directly will
still be better for positional accuracy.

89
externals/openal-soft/docs/env-vars.txt vendored Normal file
View File

@@ -0,0 +1,89 @@
Useful Environment Variables
Below is a list of environment variables that can be set to aid with running or
debugging apps that use OpenAL Soft. They should be set before the app is run.
*** Logging ***
ALSOFT_LOGLEVEL
Specifies the amount of logging OpenAL Soft will write out:
0 - Effectively disables all logging
1 - Prints out errors only
2 - Prints out warnings and errors
3 - Prints out additional information, as well as warnings and errors
ALSOFT_LOGFILE
Specifies a filename that logged output will be written to. Note that the file
will be first cleared when logging is initialized.
*** Overrides ***
ALSOFT_CONF
Specifies an additional configuration file to load settings from. These
settings will take precedence over the global and user configs, but not other
environment variable settings.
ALSOFT_DRIVERS
Overrides the drivers config option. This specifies which backend drivers to
consider or not consider for use. Please see the drivers option in
alsoftrc.sample for a list of available drivers.
ALSOFT_DEFAULT_REVERB
Specifies the default reverb preset to apply to sources. Please see the
default-reverb option in alsoftrc.sample for additional information and a list
of available presets.
ALSOFT_TRAP_AL_ERROR
Set to "true" or "1" to force trapping AL errors. Like the trap-al-error config
option, this will raise a SIGTRAP signal (or a breakpoint exception under
Windows) when a context-level error is generated. Useful when run under a
debugger as it will break execution right when the error occurs, making it
easier to track the cause.
ALSOFT_TRAP_ALC_ERROR
Set to "true" or "1" to force trapping ALC errors. Like the trap-alc-error
config option, this will raise a SIGTRAP signal (or a breakpoint exception
under Windows) when a device-level error is generated. Useful when run under a
debugger as it will break execution right when the error occurs, making it
easier to track the cause.
ALSOFT_TRAP_ERROR
Set to "true" or "1" to force trapping both ALC and AL errors.
*** Compatibility ***
__ALSOFT_HALF_ANGLE_CONES
Older versions of OpenAL Soft incorrectly calculated the cone angles to range
between 0 and 180 degrees, instead of the expected range of 0 to 360 degrees.
Setting this to "true" or "1" restores the old buggy behavior, for apps that
were written to expect the incorrect range.
__ALSOFT_ENABLE_SUB_DATA_EXT
The more widely used AL_EXT_SOURCE_RADIUS extension is incompatible with the
now-defunct AL_SOFT_buffer_sub_data extension. Setting this to "true" or "1"
restores the AL_SOFT_buffer_sub_data extension for apps that require it,
disabling AL_EXT_SOURCE_RADIUS.
__ALSOFT_REVERSE_Z
Applications that don't natively use OpenAL's coordinate system have to convert
to it before passing in 3D coordinates. Depending on how exactly this is done,
it can cause correct output for stereo but incorrect Z panning for surround
sound (i.e., sounds that are supposed to be behind you sound like they're in
front, and vice-versa). Setting this to "true" or "1" will negate the localized
Z coordinate to flip front/back panning for 3D sources.
__ALSOFT_REVERSE_Y
Same as for __ALSOFT_REVERSE_Z, but for Y (up/down) panning.
__ALSOFT_REVERSE_X
Same as for __ALSOFT_REVERSE_Z, but for X (left/right) panning.
__ALSOFT_SUSPEND_CONTEXT
Due to the OpenAL spec not being very clear about them, behavior of the
alcSuspendContext and alcProcessContext methods has varied, and because of
that, previous versions of OpenAL Soft had them no-op. Creative's hardware
drivers and the Rapture3D driver, however, use these methods to batch changes,
which some applications make use of to protect against partial updates. In an
attempt to standardize on that behavior, OpenAL Soft has changed those methods
accordingly. Setting this to "ignore" restores the previous no-op behavior for
applications that interact poorly with the new behavior.

81
externals/openal-soft/docs/hrtf.txt vendored Normal file
View File

@@ -0,0 +1,81 @@
HRTF Support
============
Starting with OpenAL Soft 1.14, HRTFs can be used to enable enhanced
spatialization for both 3D (mono) and multi-channel sources, when used with
headphones/stereo output. This can be enabled using the 'hrtf' config option.
For multi-channel sources this creates a virtual speaker effect, making it
sound as if speakers provide a discrete position for each channel around the
listener. For mono sources this provides much more versatility in the perceived
placement of sounds, making it seem as though they are coming from all around,
including above and below the listener, instead of just to the front, back, and
sides.
The default data set is based on the KEMAR HRTF data provided by MIT, which can
be found at <http://sound.media.mit.edu/resources/KEMAR.html>.
Custom HRTF Data Sets
=====================
OpenAL Soft also provides an option to use user-specified data sets, in
addition to or in place of the default set. This allows users to provide data
sets that could be better suited for their heads, or to work with stereo
speakers instead of headphones, for example.
The file format is specified below. It uses little-endian byte order.
==
ALchar magic[8] = "MinPHR03";
ALuint sampleRate;
ALubyte channelType; /* Can be 0 (mono) or 1 (stereo). */
ALubyte hrirSize; /* Can be 8 to 128 in steps of 8. */
ALubyte fdCount; /* Can be 1 to 16. */
struct {
ALushort distance; /* Can be 50mm to 2500mm. */
ALubyte evCount; /* Can be 5 to 128. */
ALubyte azCount[evCount]; /* Each can be 1 to 128. */
} fields[fdCount];
/* NOTE: ALbyte3 is a packed 24-bit sample type,
* hrirCount is the sum of all azCounts.
* channels can be 1 (mono) or 2 (stereo) depending on channelType.
*/
ALbyte3 coefficients[hrirCount][hrirSize][channels];
ALubyte delays[hrirCount][channels]; /* Each can be 0 to 63. */
==
The data layout is as follows:
The file first starts with the 8-byte marker, "MinPHR03", to identify it as an
HRTF data set. This is followed by an unsigned 32-bit integer, specifying the
sample rate the data set is designed for (OpenAL Soft will resample the HRIRs
if the output device's playback rate doesn't match).
Afterward, an unsigned 8-bit integer specifies the channel type, which can be 0
(mono, single-channel) or 1 (stereo, dual-channel). After this is another 8-bit
integer which specifies how many sample points (or finite impulse response
filter coefficients) make up each HRIR.
The following unsigned 8-bit integer specifies the number of fields used by the
data set, which must be in descending order (farthest first, closest last).
Then for each field an unsigned 16-bit short specifies the distance for that
field in millimeters, followed by an 8-bit integer for the number of
elevations. These elevations start at the bottom (-90 degrees), and increment
upwards. Following this is an array of unsigned 8-bit integers, one for each
elevation which specifies the number of azimuths (and thus HRIRs) that make up
each elevation. Azimuths start clockwise from the front, constructing a full
circle. Mono HRTFs use the same HRIRs for both ears by reversing the azimuth
calculation (ie. left = angle, right = 360-angle).
The actual coefficients follow. Each coefficient is a signed 24-bit sample.
Stereo HRTFs interleave left/right ear coefficients. The HRIRs must be
minimum-phase. This allows the use of a smaller filter length, reducing
computation.
After the coefficients is an array of unsigned 8-bit delay values as 6.2 fixed-
point integers, one for each HRIR (with stereo HRTFs interleaving left/right
ear delays). This is the propagation delay in samples a signal must wait before
being convolved with the corresponding minimum-phase HRIR filter.