summaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
author hap <happppp@users.noreply.github.com>2025-04-28 12:54:29 +0200
committer hap <happppp@users.noreply.github.com>2025-04-28 12:54:29 +0200
commitf68b2d87a12020eb3c3306411b3b88b889d8fe55 (patch)
tree119cfdbce050d14211232de8405f8ba5625df745
parent57dad8563bbc45d854fe135acbe13aa229b06846 (diff)
sound docs: small corrections after doing a quick read
-rw-r--r--docs/source/luascript/ref-common.rst11
-rw-r--r--docs/source/luascript/ref-devices.rst6
-rw-r--r--docs/source/techspecs/audio_effects.rst10
-rw-r--r--docs/source/techspecs/device_sound_interface.rst14
-rw-r--r--docs/source/techspecs/m6502.rst4
-rw-r--r--docs/source/techspecs/osd_audio.rst58
-rw-r--r--docs/source/usingmame/mamemenus.rst7
7 files changed, 62 insertions, 48 deletions
diff --git a/docs/source/luascript/ref-common.rst b/docs/source/luascript/ref-common.rst
index 1cc467fe82a..6a7c735951c 100644
--- a/docs/source/luascript/ref-common.rst
+++ b/docs/source/luascript/ref-common.rst
@@ -100,12 +100,11 @@ emu.add_machine_post_load_notifier(callback)
to a previously saved state. Returns a
:ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.register_sound_update(callback)
- Add a callback to receive new samples that have been created. THe
- samples are coming from the sound devices for which the hook
- property has been set to true. The callback gets one parameter
- which is a hash with device tag as key and a (channel-sized)
- vector of (buffer-sized) vector of
- samples in the -1..1 range.
+ Add a callback to receive new samples that have been created. The samples
+ are coming from the sound devices for which the hook property has been set
+ to true. The callback gets one parameter which is a hash with device tag
+ as key and a (channel-sized) vector of (buffer-sized) vector of samples
+ in the -1..1 range.
emu.print_error(message)
Print an error message.
emu.print_warning(message)
diff --git a/docs/source/luascript/ref-devices.rst b/docs/source/luascript/ref-devices.rst
index 23820deedef..fe25e0b0591 100644
--- a/docs/source/luascript/ref-devices.rst
+++ b/docs/source/luascript/ref-devices.rst
@@ -633,7 +633,7 @@ Sound device interface
---------------------
Wraps MAME’s ``device_sound_interface`` class which is a mix-in implemented by
-devices that inputs and/or ouputs sound.
+devices that input and/or output sound.
Instantiation
~~~~~~~~~~~~~
@@ -659,11 +659,11 @@ sound.speaker (read-only)
sound.io_positions[] (read-only)
Non-empty only for microphones and speakers, indicates the positions of
- the inputs or outputs as (x, y, z) coordinates (f.i. [-0.2, 0.0, 1.0])
+ the inputs or outputs as (x, y, z) coordinates (e.g. [-0.2, 0.0, 1.0])
sound.io_names[] (read-only)
Non-empty only for microphones and speakers, indicates the positions of
- the inputs or outputs as strings (f.i. Front Left)
+ the inputs or outputs as strings (e.g. Front Left)
sound.hook
A boolean indicating whether to tap the output samples of this device in
diff --git a/docs/source/techspecs/audio_effects.rst b/docs/source/techspecs/audio_effects.rst
index 92e2393af8e..12228b97444 100644
--- a/docs/source/techspecs/audio_effects.rst
+++ b/docs/source/techspecs/audio_effects.rst
@@ -25,7 +25,7 @@ Adding an effect requires working on four parts:
The audio_effect class in the aeffect sources provides three things:
-* an enum value to designate the effect type and which much match its
+* an enum value to designate the effect type and which must match its
position in the chain (iow, the effect chain follows the enum order),
in the .h
* the effect name in the audio_effect::effect_names array in the .cpp
@@ -36,7 +36,7 @@ The audio_effect class in the aeffect sources provides three things:
3. audio_effects/youreffect.*
-----------------------------
-This is where you implement the effect. It takes the shape of a
+This is where you implement the effect. It takes the shape of an
audio_effect_youreffect class which derives from audio_effect.
The methods to implement are:
@@ -61,7 +61,7 @@ allows to tell how many samples should still be available of the
previous input frame. Note that this number must not depend on the
parameters and only on the sample rate.
-An effect have a number of parameters that can come from three sources:
+An effect has a number of parameters that can come from three sources:
* fixed default value
* equivalent effect object from the default effect chain
@@ -72,7 +72,7 @@ gets the value of ``def`` in the constructor. When it's nullptr, the
value to use when not set by the user is the fixed one, otherwise it's
the one in ``m_default``.
-At a minimum an effect should have a parameter allowing to bypass it.
+At minimum an effect should have a parameter allowing to bypass it.
Managing a parameter uses four methods:
@@ -131,7 +131,7 @@ than the parameter setting calls are made from.
4. frontend/mame/ui/audioeffects.cpp
------------------------------------
-There it suffices to add a creation of the menu
+Here it suffices to add a creation of the menu
menu_audio_effect_youreffect in menu_audio_effects::handle. The menu
effect will pick the effect names from audio_effect (in aeffect.*).
diff --git a/docs/source/techspecs/device_sound_interface.rst b/docs/source/techspecs/device_sound_interface.rst
index 88bfbf86d35..859d2497477 100644
--- a/docs/source/techspecs/device_sound_interface.rst
+++ b/docs/source/techspecs/device_sound_interface.rst
@@ -32,19 +32,19 @@ input and output channels, the sample rate and optionally flags.
The sample rate can be SAMPLE_RATE_INPUT_ADAPTIVE,
SAMPLE_RATE_OUTPUT_ADAPTIVE or SAMPLE_RATE_ADAPTIVE. In that case the
-chosen sample rate is the highest one amongs the inputs, outputs or
+chosen sample rate is the highest one among the inputs, outputs or
both respectively. In case of loop, the chosen sample rate is the
configured global sample rate.
The only available non-default flag is STREAM_SYNCHRONOUS. When set,
the sound generation method will be called for every sample
-individually. It's necessary for dsps that run a program on every
+individually. It's necessary for DSPs that run a program on every
sample. but on the other hand it's expensive, so only to be used when
required.
-Devices can create multiple streams. It's rare though. Some yamaha
+Devices can create multiple streams. It's rare though. Some Yamaha
chips should but don't. Inputs and outputs are numbered from 0 and
-collate all streams in the order they are created.
+arrange all streams in the order they are created.
2.2 Sound input/output
@@ -140,7 +140,7 @@ a given source device.
u64 get_sound_requested_outputs_mask() const;
Those methods are useful for devices which want to behave differently
-depending on what routes are setup on them. You get either the max
+depending on what routes are set up on them. You get either the max
number of requested channel plus one (which is the number of channels
when all channels are routed, but is more useful when there are gaps)
or a mask of use for channels 0-63. Note that ``ALL_OUTPUTS`` does
@@ -158,7 +158,7 @@ Streams are endpoints associated with devices and, when connected
together, ensure the transmission of audio data between them. A
stream has a number of inputs (which can be zero) and outputs (same)
and one sample rate which is common to all inputs and outputs. The
-connections are setup at the machine configuration level and the sound
+connections are set up at the machine configuration level and the sound
system ensures mixing and resampling is done transparently.
Samples in streams are encoded as sample_t. In the current
@@ -226,7 +226,7 @@ does it with an integer ``sample`` but pre-divides it by ``max``.
what's there instead of replacing. ``get_output`` gets the currently
stored output value.
-``fill`` sets a range of the an output channel to a given ``value``.
+``fill`` sets a range of an output channel to a given ``value``.
``start`` tells where to start (default index 0), ``count`` how many
(default up to the end of the buffer).
diff --git a/docs/source/techspecs/m6502.rst b/docs/source/techspecs/m6502.rst
index 7d67423abb8..f5d55fc9af4 100644
--- a/docs/source/techspecs/m6502.rst
+++ b/docs/source/techspecs/m6502.rst
@@ -92,7 +92,7 @@ At a minimum, the class must include a constructor and an enum picking up the co
If the CPU has its own dispatch table, the class must also include the declaration (but not definition) of **disasm_entries**, **do_exec_full** and **do_exec_partial**, the declaration and definition of **disasm_disassemble** (identical for all classes but refers to the class-specific **disasm_entries** array) and include the .inc file (which provides the missing definitions). Support for the generation must also be added to CPU.mak.
-If the CPU has in addition its own opcodes, their declaration must be done through a macro, see f.i. m65c02. The .inc file will provide the definitions.
+If the CPU has in addition its own opcodes, their declaration must be done through a macro, see e.g. m65c02. The .inc file will provide the definitions.
Dispatch tables
@@ -365,7 +365,7 @@ A negative icount means that the CPU won't be able to do anything for some time
Multi-dispatch variants
-----------------------
-Some variants currently in the process of being supported change instruction set depending on an internal flag, either switching to a 16-bits mode or changing some register accesses to memory accesses. This is handled by having multiple dispatch tables for the CPU, the d<CPU>.lst not being 257 entries anymore but 256*n+1. The variable **inst_state_base** must select which instruction table to use at a given time. It must be a multiple of 256, and is in fact simply OR-ed to the first instruction byte to get the dispatch table index (aka inst_state).
+Some variants currently in the process of being supported change instruction set depending on an internal flag, either switching to a 16-bit mode or changing some register accesses to memory accesses. This is handled by having multiple dispatch tables for the CPU, the d<CPU>.lst not being 257 entries anymore but 256*n+1. The variable **inst_state_base** must select which instruction table to use at a given time. It must be a multiple of 256, and is in fact simply OR-ed to the first instruction byte to get the dispatch table index (aka inst_state).
Current TO-DO:
--------------
diff --git a/docs/source/techspecs/osd_audio.rst b/docs/source/techspecs/osd_audio.rst
index e6f1492f8f0..82e03d999ef 100644
--- a/docs/source/techspecs/osd_audio.rst
+++ b/docs/source/techspecs/osd_audio.rst
@@ -20,14 +20,16 @@ The OSD interface is designed to allow three levels of support,
depending on what the API allows and the amount of effort to expend.
Those are:
-* Level 1: One or more audio targets, only one stream allowed per target (aka exclusive mode)
+* Level 1: One or more audio targets, only one stream allowed per target
+ (aka exclusive mode)
* Level 2: One or more audio targets, multiple streams per target
-* Level 3: One or more audio targets, multiple streams per target, user-visible per-stream-channel volume control
+* Level 3: One or more audio targets, multiple streams per target, user-visible
+ per-stream-channel volume control
In any case we support having the user use an external interface to
change the target of a stream and, in level 3, change the volumes. By
support we mean storing the information in the per-game configuration
-and keeping in the internal UI in sync.
+and keeping the internal UI in sync.
Terminology
@@ -35,8 +37,11 @@ Terminology
For this module, we use the terms:
-* node: some object we can send audio to. Can be physical, like speakers, or virtual, like an effect system. It should have a unique, user-presentable name for the UI.
-* port: a channel of a node, has a name (non-unique, like "front left") and a 3D position
+* node: some object we can send audio to. Can be physical, like speakers,
+ or virtual, like an effect system. It should have a unique, user-presentable
+ name for the UI.
+* port: a channel of a node, has a name (non-unique, like "front left") and a
+ 3D position
* stream: a connection to a node with allows to send audio to it
@@ -82,10 +87,14 @@ which follows this structure,
In that code, four names must be chosen:
-* MODULE_SUPPORT_KEY some #define coming from the genie scripts to tell that this particular module can be compiled (like NO_USE_PIPEWIRE or SDLMAME_MACOSX)
-* sound_module_class is the name of the class which makes up the module (like sound_coreaudio)
-* module_name is the name to be used in -sound <xxx> to select that particular module (like coreaudio)
-* SOUND_MODULE_KEY is a symbol that represents the module internally (like SOUND_COREAUDIO)
+* MODULE_SUPPORT_KEY some #define coming from the genie scripts to tell that
+ this particular module can be compiled (like NO_USE_PIPEWIRE or SDLMAME_MACOSX)
+* sound_module_class is the name of the class which makes up the module
+ (like sound_coreaudio)
+* module_name is the name to be used in -sound <xxx> to select that particular
+ module (like coreaudio)
+* SOUND_MODULE_KEY is a symbol that represents the module internally (like
+ SOUND_COREAUDIO)
The file path needs to be added to scripts/src/osd/modules.lua in
osdmodulesbuild() and the module reference to
@@ -123,12 +132,12 @@ The full interface is:
virtual void stream_source_update(uint32_t id, int16_t *buffer, int samples_this_frame) override;
-The class sound_module provides default for minimum capabilities: one
+The class sound_module provides defaults for minimum capabilities: one
stereo target and stream at default sample rate. To support that,
only *init*, *exit* and *stream_update* need to be implemented.
*init* is called at startup and *exit* when quitting and can do
whatever they need to do. *stream_sink_update* will be called on a
-regular basis with a buffer of sample_this_frame*2*int16_t with the
+regular basis with a buffer of sample_this_frame * 2 * int16_t with the
audio to play. From this point in the documentation we'll assume more
than a single stereo channel is wanted.
@@ -139,8 +148,10 @@ Capabilities
Two methods are used by the module to indicate the level of capability
of the module:
-* split_streams_per_source() should return true when having multiple streams for one target is expected (e.g. Level 2 or 3)
-* external_per_channel_volume() should return true when the streams have per-channel volume control that can be externally controlled (e.g. Level 3)
+* split_streams_per_source() should return true when having multiple streams
+ for one target is expected (e.g. Level 2 or 3)
+* external_per_channel_volume() should return true when the streams have
+ per-channel volume control that can be externally controlled (e.g. Level 3)
Hardware information and generations
@@ -151,7 +162,7 @@ can change at any time (bluetooth devices coming and going, usb
hot-plugging...) and that the module has some way to keep tabs on what
is happening, possibly using multi-threading. To keep it
lightweight-ish, we use the concept of a *generation* which is a
-32-bits number that is incremented by the module every time something
+32-bit number that is incremented by the module every time something
changes. The core checks the current generation value at least once
every update (once per frame, usually) and if it changed asks for the
new state and detects and handles the differences. *generation*
@@ -211,17 +222,20 @@ of the host and the module. This state is:
* m_id: The numeric ID of the node
* m_rate: The minimum, maximum and preferred sample rate for the node
* m_port_names: The vector of port names
- * m_port_positions: The vector of 3D position of the ports. Refer to src/emu/speaker.h for the "standard" positions
+ * m_port_positions: The vector of 3D position of the ports. Refer to
+ src/emu/speaker.h for the "standard" positions
* m_sinks: Number of sinks (inputs)
* m_sources: Number of sources (outputs)
-* m_default_sink: ID of the node that is the current "system default" for audio output, 0 if there's no such concept
+* m_default_sink: ID of the node that is the current "system default" for
+ audio output, 0 if there's no such concept
* m_default_source: same for audio input (currently unused)
* m_streams: The vector of active streams (*stream_info*)
* m_id: The numeric ID of the stream
* m_node: The target node of the stream
- * m_volumes: empty if *external_per_channel_volume* is false, current volume value per-channel otherwise
+ * m_volumes: empty if *external_per_channel_volume* is false, current volume
+ value per-channel otherwise
IDs, for nodes and streams, are (independant) 32-bit unsigned non-zero
values associated to respectively nodes and streams. IDs should not
@@ -262,7 +276,7 @@ Input and output streams
virtual void stream_sink_update(uint32_t id, const int16_t *buffer, int samples_this_frame) override;
virtual void stream_source_update(uint32_t id, int16_t *buffer, int samples_this_frame) override;
-Streams are the concept used to send or recieve audio from/to the host
+Streams are the concept used to send or receive audio from/to the host
audio system. A stream is first opened through *stream_sink_open* for
speakers and *stream_source_open* for microphones and targets a
specific node at a specific sample rate. It is given a name for use
@@ -270,7 +284,7 @@ by the host sound services for user UI purposes (currently the game
name if split_streams_per_source is false, the
speaker_device/microphone_device tag if true). The returned ID must
be a non-zero, never-used-before for streams value in case of success.
-Failures, like when the node went away between the get_information
+Failures, like when the node went away between the *get_information*
call and the open one, should be silent and return zero.
*stream_set_volumes* is used only when *external_per_channel_volume*
@@ -321,12 +335,12 @@ Helper class *abuffer*
};
The class *abuffer* is a helper provided by *sound_module* to buffer
-audio in output or output. It automatically drops data when there is
+audio input or output. It automatically drops data when there is
an overflow and duplicates the last sample on underflow. It must
first be initialized with the number of channels, which can be
retrieved with *channels()* if needed. *push* sends
-*samples* * *channels* 16-bits samples in the buffer. *get* retrieves
-*samples* * *channels* 16-bits samples from the buffer, on a fifo basis.
+*samples* * *channels* 16-bit samples in the buffer. *get* retrieves
+*samples* * *channels* 16-bit samples from the buffer, on a FIFO basis.
It is not protected against multithreading, but uses no class
variables. So just don't read and write from one specific abuffer
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index 52745b6ff77..fc76fd1f20f 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -317,7 +317,7 @@ stereo system output.
A channel mapping maps between one channel of speaker or a microphone
and one channel of a system input or output. It can be a little
tedious, but it allows for instance to take two mono speakers and turn
-it into the left and right channels of a system output, whcih is
+it into the left and right channels of a system output, which is
useful for some cabinets.
Every mapping has a configurable volume associated.
@@ -355,6 +355,7 @@ parameters of the Default chain are fixed. The default chain allows
to create a global setup that one likes and have it applied everywhere
by default.
+
Filter effect
~~~~~~~~~~~~~
@@ -365,7 +366,7 @@ low-pass filter (defaulting to off) allows to reproduce how muffled
the sound of a number of cabinets and TVs were.
The Q factor defines how sharp the transition is, the higher the
-sharper. Over 0.7 the filter starts amplifying the frequencies arount
+sharper. Over 0.7 the filter starts amplifying the frequencies around
the cutoff though, which can be surprising.
@@ -384,7 +385,7 @@ Not implemented yet.
EQ effect
~~~~~~~~~
-The 5-band parametric equalizer allows to amplify or reduce certains
+The 5-band parametric equalizer allows to amplify or reduce certain
bands of frequency in the spectrum. The three middle filters, and
also the extreme ones if configured as "Peak", change frequencies
around the cutoff. The Q factor selects the sharpness of the peak,