The engine module is responsible for playing a song from a module. Similar to a sound driver, the engine is "ticked" or iterated for a single frame and the APU's registers are updated in order to play music.
There are two parts to this module: the engine itself and interfacing with an ApuIo.
Engine
This module provides an Engine object type that handles the performance of a data: Song (and sound effects, in the future).
To create an engine, initialize one with initEngine. Then give it a song to play via the play proc. Reference semantics are used so you will need a ref Song when playing it. Afterwards, you can call tick to perform a single tick of the engine.
There are also other procs for controlling playback, as well as informational ones for diagnostics.
ApuIo interface
The engine creates an enginestate: ApuOperation every tick. This object can be converted into register writes and then sent to an apuio: ApuIo.
Procs
proc apply(apu: var ApuIo; op: ApuOperation; wt: WaveformTable) {....raises: [].}
- Applys an ApuOperation to an ApuIo, by performing the register writes specified in op. wt is the waveform table to use for CH3 when setting waveforms. Source Edit
func frame(e: Engine): EngineFrame {....raises: [], tags: [], forbids: [].}
- Gets the current frame, or the current state, of the Engine Source Edit
func initEngine(): Engine {....raises: [], tags: [], forbids: [].}
- Constructs a new Engine. Source Edit
func isPlaying(e: Engine): bool {....raises: [], tags: [], forbids: [].}
- Determine if the engine is playing music, or if it contains a data: Song. Source Edit
proc play(e: var Engine; song: sink iref[Song]; startAt = default(SongPos)) {. ...raises: [], tags: [], forbids: [].}
-
Sets the engine to begin playback of the given song. song must not be nil, otherwise an AssertDefect will be raised. By default, the engine will play the song from the start, or pattern 0, row 0. You can override this position via the startAt parameter. If startAt is an invalid position then the engine will be halted.
Afterwards, the song can be played by calling tick periodically.
Source Edit proc takeOperation(e: var Engine): ApuOperation {....raises: [], tags: [], forbids: [].}
- Takes out the operation to be applied to an ApuIo. Should be called after tick to apply register writes to an Apu. Source Edit
proc tick(e: var Engine; itable: InstrumentTable) {....raises: [], tags: [], forbids: [].}
- Steps the engine for a single frame or 1 tick. Source Edit
proc tickAndApply(e: var Engine; itable: InstrumentTable; wtable: WaveformTable; apu: var ApuIo) {....raises: [].}
- Convenience proc that calls e.tick and apu.apply in one go. Source Edit
func trackEnvelope(e: Engine; chno: ChannelId): uint8 {....raises: [], tags: [], forbids: [].}
- Gets the track's current envelope setting, for the given channel. The envelope setting is either a volume envelope value or a waveform id. 0u8 is returned if no music is playing. Source Edit
func trackPanning(e: Engine; chno: ChannelId): uint8 {....raises: [], tags: [], forbids: [].}
- Gets the track's current panning setting, for the given channel. Panning ranges in value from 0-3. 0u8 is returned if no music is playing. Source Edit
func trackState(e: Engine; chno: ChannelId): ChannelState {....raises: [], tags: [], forbids: [].}
- Gets the current channel state of the given channel. An empty channel state is returned if no music is playing. Source Edit
func trackTimbre(e: Engine; chno: ChannelId): uint8 {....raises: [], tags: [], forbids: [].}
- Gets the track's current timbre setting, for the given channel. Timbre is a channel-specific setting that ranges in value from 0-3. 0u8 is returned if no music is playing. Source Edit
Exports
-
ApuRegister, ApuIo, toAddress, Pcm, iptr, PositiveByte, PcmF32, isNil, ==, ByteIndex, ==, ==, Tristate, ==, iref, ==, ==, add, ==, capacity, isNil, ChannelId, FixedSeq, [], ==, immutable, ==, ==, immutable, [], items, [], initTrackRow, clone, iptr, clone, isValid, isValid, capacity, trow, ==, PcmF32, []=, SomeTable, orow, TrackId, ModulePiece, hash, iref, Track, initTrackView, ==, initPattern, nextUnused, initSongList, toOption, defaultSpeed, viewTrack, toEffectCmd, duplicate, editTrack, getPatternView, shortensPattern, ==, noteNone, totalRows, InstrumentTable, ==, SongSpan, ==, isNil, [], <=, data, data, ==, all, WaveData, initInstrument, hash, initModule, SomeData, add, ==, instrumentNone, capacity, editPattern, NoteColumn, len, defaultRpb, len, trackLen=, newModule, len, isValid, isValid, has, initWaveformTable, initWaveform, items, Pattern, [], ByteIndex, ==, Tickrate, InstrumentColumn, initEffect, allocateTracks, isValid, getRow, [], initLoopPoint, unitSpeed, value, asSlice, PatternView, OrderRow, toOption, immutable, isValid, Effect, removeUnusedTracks, $, effectNone, uniqueIds, []=, [], initTrack, estimateSpeed, SongPos, <, initOrderRow, tempo, revisionMinor, defaultTickrate, =copy, len, getTickrate, items, [], has, $, noLoopPoint, effectCharMap, SequenceKind, ==, toSpeed, tempo, instrumentColumn, items, [], [], $, PositiveByte, effectiveTickrate, toFloat, SongList, clone, Speed, LoopPoint, Tristate, ==, mget, OrderLen, viewPattern, getRow, songSpan, [], TableId, getTrackView, patternLen, Order, noteColumn, ==, [], ==, initTrack, items, trackIds, totalRows, Pcm, EffectCmd, totalTracks, ==, removeAllTracks, Instrument, defaultTrackLen, nextAvailableId, value, $, next, $, trackLen, ==, initSong, mitems, songSpan, isEmpty, ==, SomePattern, effectCmdToChar, toInfoString, immutable, mitems, ==, initLoopPoint, System, SequenceLen, isNil, isValid, isValid, TrackRow, newSong, initSequence, defaultRpm, getPattern, WaveformTable, add, isValid, contains, SomeTrack, remove, Waveform, initInstrumentTable, ==, InfoString, isValid, $, EffectCounts, TrackLen, ==, PatternRow, toView, setLen, Module, ==, tempo, getTrack, items, Song, noteColumn, [], initOrder, version, len, Sequence, TrackView, rangeSpeed, ChannelId, add, hertz, get, FixedSeq, toView, ==, patternLen, songPos, revisionMajor, Order, ChannelUpdate, mget, getTickrate, trow, ==, SomeTable, TrackId, ModulePiece, hash, updateAll, Track, [], initPattern, nextUnused, ==, $, toEffectCmd, ChannelAction, getPatternView, items, isHalted, ==, SongSpan, duplicate, data, ==, WaveData, tick, TrackerResult, SomeData, ==, capacity, editPattern, ==, isEnabled, defaultRpb, hash, len, isValid, initWaveformTable, initWaveform, removeUnusedTracks, ByteIndex, get, Tickrate, InstrumentColumn, patternRepeat=, isValid, getRow, [], toOption, getPath, pos, initCounter, trackLen, effectsFilter, $, effectNone, []=, estimateSpeed, initOrderRow, tempo, ==, tick, ChannelState, uniqueIds, SequenceKind, ==, toSpeed, tempo, $, items, [], [], Tracker, viewPattern, toFloat, SongList, clone, Speed, Tristate, getOp, $, patternLen, clone, speed, initTrack, ApuOperation, shortensPattern, Pcm, [], totalTracks, noteNone, trackLen=, removeAllTracks, Instrument, defaultTrackLen, value, ==, revisionMinor, len, EffectCounts, ==, initSong, songSpan, totalRows, isRunning, effectCmdToChar, immutable, mitems, SequenceLen, isNil, isValid, defaultRpm, WaveformTable, <=, contains, SomeTrack, remove, data, initInstrumentTable, ==, TrackLen, runtime, PatternRow, Module, tempo, getTrack, jump, [], trackerResult, ==, len, SongPath, UpdateFlag, rangeSpeed, FixedSeq, runtime, ==, songPos, revisionMajor, clone, iptr, allocateTracks, isValid, isValid, editTrack, isEmpty, PcmF32, orow, iref, initTrackView, ==, defaultSpeed, all, viewTrack, initTrack, isValid, capacity, ==, toView, InstrumentTable, patternRepeat, [], Counter, initInstrument, noteColumn, initModule, mitems, add, instrumentNone, NoteColumn, newModule, len, isValid, has, <, Pattern, initTracker, ==, =copy, initEffect, unitSpeed, value, OrderRow, immutable, isValid, Effect, noCounter, noLoopPoint, ==, TrackerStatus, runtime, SongPos, ==, isValid, defaultTickrate, len, has, $, initChannelState, effectCharMap, [], instrumentColumn, PositiveByte, effectiveTickrate, items, ==, LoopPoint, toOption, halt, OrderLen, PatternView, songSpan, [], TableId, getTrackView, initTrackRow, effectsFilter=, [], items, trackIds, totalRows, next, EffectCmd, version, ==, getRow, initLoopPoint, nextAvailableId, EngineFrame, patternLen, SomePattern, initLoopPoint, System, UpdateFlags, TrackRow, newSong, initSequence, getPattern, toView, add, isValid, filter, initSongList, asSlice, isNil, Waveform, InfoString, isValid, $, ==, setLen, items, Song, noteColumn, initOrder, []=, Sequence, toInfoString, TrackView, ChannelId, add, hertz