jar_xm.h File Reference

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <limits.h>
#include <string.h>
#include <stdbool.h>

Go to the source code of this file.

Macros
#define	JAR_XM_DEBUG   0
#define	JAR_XM_LINEAR_INTERPOLATION   1
#define	JAR_XM_DEFENSIVE   1
#define	JAR_XM_RAMPING   1

Typedefs
typedef struct jar_xm_context_s	jar_xm_context_t

Functions
int	jar_xm_create_context_from_file (jar_xm_context_t **ctx, uint32_t rate, const char *filename)
	Create a XM context. More...
int	jar_xm_create_context (jar_xm_context_t **, const char *moddata, uint32_t rate)
	Create a XM context. More...
int	jar_xm_create_context_safe (jar_xm_context_t **, const char *moddata, size_t moddata_length, uint32_t rate)
	Create a XM context. More...
void	jar_xm_free_context (jar_xm_context_t *)
	Free a XM context created by jar_xm_create_context(). More...
void	jar_xm_generate_samples (jar_xm_context_t *, float *output, size_t numsamples)
	Play the module and put the sound samples in an output buffer. More...
void	jar_xm_generate_samples_16bit (jar_xm_context_t *ctx, short *output, size_t numsamples)
	Play the module, resample from 32 bit to 16 bit, and put the sound samples in an output buffer. More...
void	jar_xm_generate_samples_8bit (jar_xm_context_t *ctx, char *output, size_t numsamples)
	Play the module, resample from 32 bit to 8 bit, and put the sound samples in an output buffer. More...
void	jar_xm_set_max_loop_count (jar_xm_context_t *, uint8_t loopcnt)
	Set the maximum number of times a module can loop. More...
uint8_t	jar_xm_get_loop_count (jar_xm_context_t *)
	Get the loop count of the currently playing module. More...
bool	jar_xm_mute_channel (jar_xm_context_t *, uint16_t, bool)
	Mute or unmute a channel. More...
bool	jar_xm_mute_instrument (jar_xm_context_t *, uint16_t, bool)
	Mute or unmute an instrument. More...
const char *	jar_xm_get_module_name (jar_xm_context_t *)
	Get the module name as a NUL-terminated string. More...
const char *	jar_xm_get_tracker_name (jar_xm_context_t *)
	Get the tracker name as a NUL-terminated string. More...
uint16_t	jar_xm_get_number_of_channels (jar_xm_context_t *)
	Get the number of channels. More...
uint16_t	jar_xm_get_module_length (jar_xm_context_t *)
	Get the module length (in patterns). More...
uint16_t	jar_xm_get_number_of_patterns (jar_xm_context_t *)
	Get the number of patterns. More...
uint16_t	jar_xm_get_number_of_rows (jar_xm_context_t *, uint16_t)
	Get the number of rows of a pattern. More...
uint16_t	jar_xm_get_number_of_instruments (jar_xm_context_t *)
	Get the number of instruments. More...
uint16_t	jar_xm_get_number_of_samples (jar_xm_context_t *, uint16_t)
	Get the number of samples of an instrument. More...
void	jar_xm_get_playing_speed (jar_xm_context_t *, uint16_t *bpm, uint16_t *tempo)
	Get the current module speed. More...
void	jar_xm_get_position (jar_xm_context_t *, uint8_t *pattern_index, uint8_t *pattern, uint8_t *row, uint64_t *samples)
	Get the current position in the module being played. More...
uint64_t	jar_xm_get_latest_trigger_of_instrument (jar_xm_context_t *, uint16_t)
	Get the latest time (in number of generated samples) when a particular instrument was triggered in any channel. More...
uint64_t	jar_xm_get_latest_trigger_of_sample (jar_xm_context_t *, uint16_t instr, uint16_t sample)
	Get the latest time (in number of generated samples) when a particular sample was triggered in any channel. More...
uint64_t	jar_xm_get_latest_trigger_of_channel (jar_xm_context_t *, uint16_t)
	Get the latest time (in number of generated samples) when any instrument was triggered in a given channel. More...
uint64_t	jar_xm_get_remaining_samples (jar_xm_context_t *)
	Get the number of remaining samples. More...

Macro Definition Documentation

JAR_XM_DEBUG

#define JAR_XM_DEBUG   0

Definition at line 54 of file jar_xm.h.

JAR_XM_DEFENSIVE

#define JAR_XM_DEFENSIVE   1

Definition at line 56 of file jar_xm.h.

JAR_XM_LINEAR_INTERPOLATION

#define JAR_XM_LINEAR_INTERPOLATION   1

Definition at line 55 of file jar_xm.h.

JAR_XM_RAMPING

#define JAR_XM_RAMPING   1

Definition at line 57 of file jar_xm.h.

Typedef Documentation

jar_xm_context_t

typedef struct jar_xm_context_s jar_xm_context_t

Definition at line 77 of file jar_xm.h.

Function Documentation

jar_xm_create_context()

int jar_xm_create_context	(	jar_xm_context_t **	,
		const char *	moddata,
		uint32_t	rate
	)

Create a XM context.

Parameters

moddata	the contents of the module
rate	play rate in Hz, recommended value of 48000

Returns

0 on success

1 if module data is not sane

2 if memory allocation failed

Deprecated:

This function is unsafe!

See also

jar_xm_create_context_safe()

jar_xm_create_context_from_file()

int jar_xm_create_context_from_file	(	jar_xm_context_t **	ctx,
		uint32_t	rate,
		const char *	filename
	)

Create a XM context.

Parameters

moddata	the contents of the module
rate	play rate in Hz, recommended value of 48000

Returns

0 on success

1 if module data is not sane

2 if memory allocation failed

3 unable to open input file

4 fseek() failed

5 fread() failed

6 unkown error

Deprecated:

This function is unsafe!

See also

jar_xm_create_context_safe()

jar_xm_create_context_safe()

int jar_xm_create_context_safe	(	jar_xm_context_t **	,
		const char *	moddata,
		size_t	moddata_length,
		uint32_t	rate
	)

Create a XM context.

Parameters

moddata	the contents of the module
moddata_length	the length of the contents of the module, in bytes
rate	play rate in Hz, recommended value of 48000

Returns

0 on success

1 if module data is not sane

2 if memory allocation failed

jar_xm_free_context()

void jar_xm_free_context

(

jar_xm_context_t *

)

Free a XM context created by jar_xm_create_context().

jar_xm_generate_samples()

void jar_xm_generate_samples	(	jar_xm_context_t *	,
		float *	output,
		size_t	numsamples
	)

Play the module and put the sound samples in an output buffer.

Parameters

output	buffer of 2*numsamples elements (A left and right value for each sample)
numsamples	number of samples to generate

Referenced by jar_xm_generate_samples_16bit(), and jar_xm_generate_samples_8bit().

jar_xm_generate_samples_16bit()

void jar_xm_generate_samples_16bit	(	jar_xm_context_t *	ctx,
		short *	output,
		size_t	numsamples
	)

Play the module, resample from 32 bit to 16 bit, and put the sound samples in an output buffer.

Parameters

output	buffer of 2*numsamples elements (A left and right value for each sample)
numsamples	number of samples to generate

Definition at line 138 of file jar_xm.h.

{
    float* musicBuffer = malloc((2*numsamples)*sizeof(float));
    jar_xm_generate_samples(ctx, musicBuffer, numsamples);
 
    if(output){
        size_t x;
        for(x=0;x<2*numsamples;x++)
            output[x] = (short)(musicBuffer[x] * SHRT_MAX);
    }
 
    free(musicBuffer);
}

jar_xm_generate_samples_8bit()

void jar_xm_generate_samples_8bit	(	jar_xm_context_t *	ctx,
		char *	output,
		size_t	numsamples
	)

Play the module, resample from 32 bit to 8 bit, and put the sound samples in an output buffer.

Parameters

output	buffer of 2*numsamples elements (A left and right value for each sample)
numsamples	number of samples to generate

Definition at line 157 of file jar_xm.h.

{
    float* musicBuffer = malloc((2*numsamples)*sizeof(float));
    jar_xm_generate_samples(ctx, musicBuffer, numsamples);
 
    if(output){
        size_t x;
        for(x=0;x<2*numsamples;x++)
            output[x] = (char)(musicBuffer[x] * CHAR_MAX);
    }
 
    free(musicBuffer);
}

jar_xm_get_latest_trigger_of_channel()

uint64_t jar_xm_get_latest_trigger_of_channel	(	jar_xm_context_t *	,
		uint16_t
	)

Get the latest time (in number of generated samples) when any instrument was triggered in a given channel.

Note

Channel numbers go from 1 to jar_xm_get_number_of_channels(...).

jar_xm_get_latest_trigger_of_instrument()

uint64_t jar_xm_get_latest_trigger_of_instrument	(	jar_xm_context_t *	,
		uint16_t
	)

Get the latest time (in number of generated samples) when a particular instrument was triggered in any channel.

Note

Instrument numbers go from 1 to jar_xm_get_number_of_instruments(...).

jar_xm_get_latest_trigger_of_sample()

uint64_t jar_xm_get_latest_trigger_of_sample	(	jar_xm_context_t *	,
		uint16_t	instr,
		uint16_t	sample
	)

Get the latest time (in number of generated samples) when a particular sample was triggered in any channel.

Note

Instrument numbers go from 1 to jar_xm_get_number_of_instruments(...).

Sample numbers go from 0 to jar_xm_get_nubmer_of_samples(...,instr)-1.

jar_xm_get_loop_count()

uint8_t jar_xm_get_loop_count

(

jar_xm_context_t *

)

Get the loop count of the currently playing module.

This value is 0 when the module is still playing, 1 when the module has looped once, etc.

jar_xm_get_module_length()

uint16_t jar_xm_get_module_length

(

jar_xm_context_t *

)

Get the module length (in patterns).

jar_xm_get_module_name()

const char* jar_xm_get_module_name

(

jar_xm_context_t *

)

Get the module name as a NUL-terminated string.

jar_xm_get_number_of_channels()

uint16_t jar_xm_get_number_of_channels

(

jar_xm_context_t *

)

Get the number of channels.

jar_xm_get_number_of_instruments()

uint16_t jar_xm_get_number_of_instruments

(

jar_xm_context_t *

)

Get the number of instruments.

jar_xm_get_number_of_patterns()

uint16_t jar_xm_get_number_of_patterns

(

jar_xm_context_t *

)

Get the number of patterns.

jar_xm_get_number_of_rows()

uint16_t jar_xm_get_number_of_rows	(	jar_xm_context_t *	,
		uint16_t
	)

Get the number of rows of a pattern.

Note

Pattern numbers go from 0 to jar_xm_get_number_of_patterns(...)-1.

jar_xm_get_number_of_samples()

uint16_t jar_xm_get_number_of_samples	(	jar_xm_context_t *	,
		uint16_t
	)

Get the number of samples of an instrument.

Note

Instrument numbers go from 1 to jar_xm_get_number_of_instruments(...).

jar_xm_get_playing_speed()

void jar_xm_get_playing_speed	(	jar_xm_context_t *	,
		uint16_t *	bpm,
		uint16_t *	tempo
	)

Get the current module speed.

Parameters

bpm	will receive the current BPM
tempo	will receive the current tempo (ticks per line)

jar_xm_get_position()

void jar_xm_get_position	(	jar_xm_context_t *	,
		uint8_t *	pattern_index,
		uint8_t *	pattern,
		uint8_t *	row,
		uint64_t *	samples
	)

Get the current position in the module being played.

Parameters

pattern_index	if not NULL, will receive the current pattern index in the POT (pattern order table)
pattern	if not NULL, will receive the current pattern number
row	if not NULL, will receive the current row
samples	if not NULL, will receive the total number of generated samples (divide by sample rate to get seconds of generated audio)

jar_xm_get_remaining_samples()

uint64_t jar_xm_get_remaining_samples

(

jar_xm_context_t *

)

Get the number of remaining samples.

Divide by 2 to get the number of individual LR data samples.

Note

This is the remaining number of samples before the loop starts module again, or halts if on last pass.

This function is very slow and should only be run once, if at all.

jar_xm_get_tracker_name()

const char* jar_xm_get_tracker_name

(

jar_xm_context_t *

)

Get the tracker name as a NUL-terminated string.

jar_xm_mute_channel()

bool jar_xm_mute_channel	(	jar_xm_context_t *	,
		uint16_t	,
		bool
	)

Mute or unmute a channel.

Note

Channel numbers go from 1 to jar_xm_get_number_of_channels(...).

Returns

whether the channel was muted.

jar_xm_mute_instrument()

bool jar_xm_mute_instrument	(	jar_xm_context_t *	,
		uint16_t	,
		bool
	)

Mute or unmute an instrument.

Note

Instrument numbers go from 1 to jar_xm_get_number_of_instruments(...).

Returns

whether the instrument was muted.

jar_xm_set_max_loop_count()

void jar_xm_set_max_loop_count	(	jar_xm_context_t *	,
		uint8_t	loopcnt
	)

Set the maximum number of times a module can loop.

After the specified number of loops, calls to jar_xm_generate_samples will only generate silence. You can control the current number of loops with jar_xm_get_loop_count().

Parameters

loopcnt

maximum number of loops. Use 0 to loop indefinitely.