Struct exmod::Context

pub struct Context(_);

Module context.

Can contain only one module and provides functions for manipulating it.

Implementations

impl Context

pub fn new(module: &[u8], rate: u32) -> Result<Self, ContextError>

Create a context.

The module parameter sets a contents of the module. The rate parameter specifies a sample rate (in Hz) with which samples will be generated.

Example

use exmod::Context;

let context = Context::new(include_bytes!("module.xm"), 44100).unwrap();

// And start working with it...

pub fn as_ptr(&mut self) -> ContextPointer

Returns a raw pointer to the inner context.

pub unsafe fn from_ptr(pointer: ContextPointer) -> Self

Creates a context directly from the raw pointer of another context.

Safety

pointer must be previously allocated via new and then as_ptr functions or their unsafe equivalent - xm_create_context_safe.

pub fn generate_samples(&mut self, samples: &mut [f32])

Play the module and put a generated samples in the samples slice.

Creates silence if the loop count specified by set_max_loop_count is reached. By default plays endlessly.

Requires mutability because generating samples moves a playback cursor within context.

Example

See examples repository folder for comprehensive examples.

pub fn current_loop_number(&self) -> u8

Get the current number of playback loops of the module.

The number will increase with each loop. When the maximum number of loops is reached, calls to generate_samples will only generate silence. You can set number of maximum loops with set_max_loop_count.

pub fn set_max_loop_count(&mut self, count: u8)

Set the max number of playback loops of the module.

Set to 0 to loop indefinitely. By default max loop count is 0 (i. e. infinity).

See also current_loop_number.

pub fn number_of_channels(&self) -> u16

Get the number of module channels.

pub fn module_length(&self) -> u16

Get the module length.

pub fn number_of_patterns(&self) -> u16

Get the number of module patterns.

pub fn number_of_rows(&self, pattern: u16) -> Result<u16, OutOfBoundsError>

Get the number of module rows.

pub fn number_of_instruments(&self) -> u16

Get the number of module instruments.

pub fn number_of_samples(
    &self,
    instrument: u16
) -> Result<u16, OutOfBoundsError>

Get the number of samples of the given instrument.

pub fn panning_of_channel(&self, channel: u16) -> Result<f32, OutOfBoundsError>

Get the panning of the given channel.

Returns a panning between 0 (L) and 1 (R).

pub fn volume_of_channel(&self, channel: u16) -> Result<f32, OutOfBoundsError>

Get the volume of the given channel.

Returns a volume between 0 or 1.

pub fn frequency_of_channel(&self, channel: u16) -> Result<f32, ChannelError>

Get the frequency in Hz of the given channel.

pub fn is_channel_active(&self, channel: u16) -> Result<bool, OutOfBoundsError>

Check if the channel is active.

pub fn latest_trigger_of_instrument(
    &self,
    instrument: u16
) -> Result<u64, OutOfBoundsError>

Get the latest trigger of the given instrument.

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

pub fn latest_trigger_of_sample(
    &self,
    instrument: u16,
    sample: u16
) -> Result<u64, OutOfBoundsError>

Get the latest trigger of the given sample of the given instrument.

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

pub fn latest_trigger_of_channel(
    &self,
    channel: u16
) -> Result<u64, OutOfBoundsError>

Get the latest trigger of the given channel.

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

pub fn playing_speed(&self) -> Speed

Get the module playing speed.

pub fn position(&self) -> Position

Get the current playback position.

pub fn mute_channel(
    &mut self,
    channel: u16,
    mute: bool
) -> Result<bool, OutOfBoundsError>

Mute the given channel.

pub fn mute_instrument(
    &mut self,
    instrument: u16,
    mute: bool
) -> Result<bool, OutOfBoundsError>

Mute the given instrument.

pub unsafe fn seek(&mut self, pattern_index: u8, row: u8, tick: u16)

Seek the playback cursor to the specified position.

Safety

Seek feature is broken by design and usually leads to access violation error, use at your own risk.

impl Context

pub fn module_name(&self) -> Result<&str, Utf8Error>

Get the module name.

pub fn tracker_name(&self) -> Result<&str, Utf8Error>

Get the the name of the tracker in which the module was created.

Trait Implementations

impl Debug for Context

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

Formats the value using the given formatter.

impl Drop for Context

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Context

impl Sync for Context