Home Download Musics Developers
API Sources Tools File Format Technicals

YM-2149 emulator
[io68 library documentation.]


Detailed Description

The YM-2149 (Atari-ST soundchip) emulator.


Files

file  ym_io.h
 YM-2149 emulator plugin header.

file  ymemul.h
 YM-2149 emulator header.


Data Structures

struct  ym2149_t
 YM-2149 internal data structure. More...


YM-2149 registers

#define YM_BASEPERL   0
 YM-2149 LSB period base (canal A).

#define YM_BASEPERH   1
 YM-2149 MSB period base (canal A).

#define YM_BASEVOL   8
 YM-2149 volume base register (canal A).

#define YM_PERL(N)   (YM_BASEPERL+(N)*2)
 Canal #N LSB period.

#define YM_PERH(N)   (YM_BASEPERH+(N)*2)
 Canal #N MSB periodr.

#define YM_VOL(N)   (YM_BASEVOL+(N))
 Canal #N volume.

#define YM_NOISE   6
 Noise period.

#define YM_MIXER   7
 Mixer control.

#define YM_ENVL   11
 Volume envelop LSB period.

#define YM_ENVH   12
 Volume envelop MSB period.

#define YM_ENVTYPE   13
 Volume envelop wave form.

#define YM_ENVSHAPE   13
 Volume envelop wave form.


Initialization functions

unsigned int YM_sampling_rate (unsigned int f)
 Set/get output buffer replay frequency.

int YM_reset (void)
 Yamaha-2149 hardware reset.

int YM_init (void)
 Yamaha-2149 first one first initialization.


Emulation functions

unsigned int YM_mix (cycle68_t cycle2mix)
 Execute Yamaha-2149 emulation.

u32YM_get_buffer (void)
 Yamaha get buffer.

void YM_subcycle (cycle68_t subcycle)
 Change YM cycle counter base.


YM-2149 register access functions

void YM_writereg (u8 reg, u8 v, cycle68_t cycle)
 Write in YM register.

u8 YM_readreg (u8 reg, cycle68_t cycle)
 Read a YM-2119 register.

int YM_get_activevoices (void)
 Get voices status.

void YM_set_activeVoices (int v)
 Set voices status.


Yamaha-2149 IO plugin

io68_t ym_io
 Yamaha-2149 IO plugin instance.


Variables

ym2149_t ym
 YM-2149 emulator internal data.


Function Documentation

unsigned int YM_sampling_rate unsigned int  f  ) 
 

Set/get output buffer replay frequency.

The YM_sampling_rate() function set YM-2149 emulator sampling rate. If f is 0 the current sampling rate is returned without change.

Parameters:
f Sampling rate (in Hz) in the range [SAMPLING_RATE_MIN..SAMPLING_RATE_MAX]. 0 is used to read current value.
Returns:
sampling rate used clampled in the range [SAMPLING_RATE_MIN..SAMPLING_RATE_MAX].

int YM_reset void   ) 
 

Yamaha-2149 hardware reset.

The YM_reset() reset function perform a YM-2149 reset. It performs following operations :

  • all register zeroed
  • mixer is set to 077 (no sound and no noise)
  • envelop shape is set to 0xA (/\)
  • control register is set to 0
  • internal periods counter are zeroed

Returns:
error-code (always success)
Return values:
0 Success

int YM_init void   ) 
 

Yamaha-2149 first one first initialization.

The YM_init() must be call before all other YM functions. It performs following operations :

  • Init envelop data.
  • Init output level (volume) table.
  • Hardware reset
  • Set replay frequency to default (44100 Hz)

Returns:
error-code (always success)
Return values:
0 Success
See also:
YM_reset()

unsigned int YM_mix cycle68_t  cycle2mix  ) 
 

Execute Yamaha-2149 emulation.

The YM_mix() function execute Yamaha-2149 emulation for a given number of cycle. Clock frequency is based on Atari-ST 68K at 8MHz. This function fill internal mix-buffer, that could be retrieve by YM_get_buffer() function and returns the number of sample mixed. The register update lists are flushed to perform a cycle precision emulation.

Warning:
The emulator used an internal round error counter, so the return value could be different from one call to another even the number of cycle is the same.
Returns:
Number of sample in output mix-buffer
See also:
YM_get_buffer()

u32* YM_get_buffer void   ) 
 

Yamaha get buffer.

The YM_get_buffer() function returns a pointer to the current PCM ouput buffer. Currently it returns a static buffer so the address is always the same but this could change in the future and it is safer to call it after each YM_mix() function call.

Output buffer samples are unsigned 16 bit machine endian values stored in a 32 bit data. Copying LSW value to the MSW transform it in a stereo sample.

Returns:
Pointer to a 32-bit value output buffer.
Return values:
0 No output buffer (currently impossible).
See also:
YM_mix()

void YM_subcycle cycle68_t  subcycle  ) 
 

Change YM cycle counter base.

The YM_subcycle() function allow to corrige the internal cycle counter to prevent overflow. Because the number of cycle could grow very quickly, it is neccessary to get it down from time to time.

Parameters:
subcycle Number of cycle to substract to current cycle counter.

void YM_writereg u8  reg,
u8  v,
cycle68_t  cycle
 

Write in YM register.

The YM_writereg() function must be call to write an YM-2149 register. The YM-2149 emulator do not really write register, but store changes in separate list depending of the register nature and dependencies. There are 3 list of update (sound, noise and envelop). This method allow to perform a very efficient cycle precise emulation. For this reason, the YM-2149 must not be read directly but toward the YM_readreg() function.

Parameters:
reg YM-2149 register to write
v Value to write
cycle Cycle number this access occurs
See also:
YM_readreg();

u8 YM_readreg u8  reg,
cycle68_t  cycle
 

Read a YM-2119 register.

The YM_readreg() function must be call to read an YM-2149 register. For the reasons explained in YM_writereg(), register must not be read directly.

Parameters:
reg YM-2149 register to read
cycle Cycle number this access occurs
Returns:
Register value at given cycle
See also:
YM_writereg();

int YM_get_activevoices void   ) 
 

Get voices status.

The YM_get_activevoices() function return activation status for each voices (canals) of the YM.

Returns:
voices activation status. -bit#0: canal A (0:off) -bit#1: canal B (0:off) -bit#2: canal C (0:off)
See also:
void YM_set_activeVoices(int v);

void YM_set_activeVoices int  v  ) 
 

Set voices status.

The YM_set_activevoices() function activates or desactivates each voices (canals) of the YM.

Parameters:
v new voices activation status. -bit#0: canal A (0:off) -bit#1: canal B (0:off) -bit#2: canal C (0:off)
See also:
void YM_get_activeVoices(int v);