Struct ym_file_parser::YmFrame

pub struct YmFrame {
    pub data: [u8; 16],
}

This type represent the state of the AY/YM chipset registers and contain additional information about special effects.

X - AY/YM register data.
S - Controls special effects.
P - Frequency pre-divisor.
F - Frequency divisor.
- - Unused.
----------------------------------------------------------
     b7 b6 b5 b4 b3 b2 b1 b0  Register description
 0:  X  X  X  X  X  X  X  X   Fine period voice A
 1:  S  S  S  S  X  X  X  X   Coarse period voice A
 2:  X  X  X  X  X  X  X  X   Fine period voice B
 3:  S  S  S  S  X  X  X  X   Coarse period voice B
 4:  X  X  X  X  X  X  X  X   Fine period voice C
 5:  -  -  -  -  X  X  X  X   Coarse period voice C
 6:  P  P  P  X  X  X  X  X   Noise period
 7:  X  X  X  X  X  X  X  X   Mixer control
 8:  P  P  P  X  X  X  X  X   Volume voice A
 9:  -  -  -  X  X  X  X  X   Volume voice B
10:  -  -  -  X  X  X  X  X   Volume voice C
11:  X  X  X  X  X  X  X  X   Envelope fine period
12:  X  X  X  X  X  X  X  X   Envelope coarse period
13:  x  x  x  x  X  X  X  X   Envelope shape
----------------------------------------------------------
virtual registers to store extra data for special effects:
----------------------------------------------------------
14:  F  F  F  F  F  F  F  F   Frequency divisor for S in 1
15:  F  F  F  F  F  F  F  F   Frequency divisor for S in 3

The AY/YM Envelope shape register is modified only if the value of the 13 frame register is not equal to 0xff.

Special effects

The frequency of a special effect is encoded as (2457600 / P) / F.

The divisor F is an unsigned 8-bit integer.

The pre-divisor P is encoded as:

PPP	pre-divisor value
000	Timer off
001	4
010	10
011	16
100	50
101	64
110	100
111	200

• The pre-divisor P in register 6 matches effect controlled by register 1.
• The divisor F in register 14 matches effect controlled by register 1.
• The pre-divisor P in register 8 matches effect controlled by register 3.
• The divisor F in register 15 matches effect controlled by register 3.

If an effect is active, the additional data resides in X bits in the Volume register of the relevant voice:

• For the SID voice and Sinus SID effects the 4 lowest X bits determine the effect’s volume.
• For the Sync Buzzer the 4 lowest X bits determine the effect’s Envelope shape.
• For the DIGI-DRUM effect the 5 X bits determine the played sample number.
• The DIGI-DRUM sample plays until its end or if it’s overridden by another effect.
• All other effects are active only for the duration of a single frame.
• When the DIGI-DRUM is active the volume register from the frame for the relevant voice is being ignored and the relevant voice mixer tone and noise bits are forced to be set.

The control bits of special effects are interpreted differently depending on the YM-file verion.

YM6!

The S bits in registers 1 and 3 controls any two of the selectable effects:

b7 b6 b5 b4 
-  -  0  0  effect disabled
-  -  0  1  effect active on voice A
-  -  1  0  effect active on voice B
-  -  1  1  effect active on voice C
0  0  -  -  select SID voice effect
0  1  -  -  select DIGI-DRUM effect
1  0  -  -  select Sinus SID effect
1  1  -  -  select Sync Buzzer effect

YM4!/YM5!

The S bits in register 1 controls the SID voice effect. The S bits in register 3 controls the DIGI-DRUM effect.

b7 b6 b5 b4 
-  -  0  0  effect disabled
-  -  0  1  effect active on voice A
-  -  1  0  effect active on voice B
-  -  1  1  effect active on voice C
-  0  -  -  SID voice timer continues, ignored for DIGI-DRUM
-  1  -  -  SID voice timer restarts, ignored for DIGI-DRUM

YM3!

There are no special effects in this version.

YM2!

Only the DIGI-DRUM effect is recognized in this format. It is being played on voice C, and uses one of the 40 predefined samples.

• The effect starts when the highest bit (7) of the Volume voice C register (10) is 1.
• The sample number is taken from the lowest 7 bits of the Volume voice C register (10).
• The effect frequency is calculated by (2457600 / 4) / X, where X is the unsigned 8-bit value stored in the register 12 of the frame.
• The value of AY/YM chipset registers 11, 12 and 13 is only written if the value of the frame register 13 is not equal to 0xFF.
• The register 12 of the AY/YM chipset is always being set to 0 in this format.
• The register 13 of the AY/YM chipset is always being set to 0x10 in this format.

Fields

data: [u8; 16]

Frame data.

Implementations

impl YmFrame

pub fn fx0(&self) -> FxCtrlFlags

Returns special effect control flags from the register 1.

pub fn fx1(&self) -> FxCtrlFlags

Returns special effect control flags from the register 3.

pub fn vol(&self, chan: u8) -> u8

Returns the value of the volume register for the indicated chan.

The 2 lowest bits of chan indicate the voice channel:

 b1 b0 voice channel
 0  0  A
 0  1  B
 1  0  C
 1  1  invalid (panics in debug mode)

pub fn timer_divisor0(&self) -> Option<NonZeroU32>

Calculates the timer divsor for the special effect fx0.

pub fn timer_divisor1(&self) -> Option<NonZeroU32>

Calculates the timer divsor for the special effect fx1.

Trait Implementations

impl Clone for YmFrame

fn clone(&self) -> YmFrame

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for YmFrame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for YmFrame

fn default() -> YmFrame

Returns the “default value” for a type.

impl Copy for YmFrame