diff --git a/docs/0CC vs FT effects type order.md b/docs/0CC vs FT effects type order.md new file mode 100644 index 00000000..d4881bc2 --- /dev/null +++ b/docs/0CC vs FT effects type order.md @@ -0,0 +1,33 @@ +# 0CC vs FT effect type order + +0CC for some reason uses a slightly different effects type order within the tracker, but converts to FT 050B+ effects type order when saved to a file. + +In Dn-FT v.0.5.0.0, this conversion logic was disturbed, resulting in 0CC effects type order not being properly converted back to FT 050B+ when saving. This issue has been fixed in [commit df78460](https://github.com/Dn-Programming-Core-Management/Dn-FamiTracker/commit/df78460aae403daf2bb68891c788248bbc8a8a02). + +my guess is cross compatibility with earlier 0CC versions that didn't respect FT 050B+'s effect type order? +we can't do anything to change it, now. + +``` +After EF_SUNSOFT_ENV_LO (Jxx S5B), +FT order: + EF_NOTE_RELEASE (Lxx) + EF_GROOVE (Oxx) + EF_TRANSPOSE (Txy) + EF_N163_WAVE_BUFFER (Zxx N163) + EF_FDS_VOLUME (Exx FDS) + EF_FDS_MOD_BIAS (Zxx FDS) + EF_SUNSOFT_NOISE (Wxx S5B) + EF_VRC7_PORT (Hxx VRC7) + EF_VRC7_WRITE (Ixx VRC7) + +0CC order: + EF_SUNSOFT_NOISE (Wxx S5B) + EF_VRC7_PORT (Hxx VRC7) + EF_VRC7_WRITE (Ixx VRC7) + EF_NOTE_RELEASE (Lxx) + EF_GROOVE (Oxx) + EF_TRANSPOSE (Txy) + EF_N163_WAVE_BUFFER (Zxx N163) + EF_FDS_VOLUME (Exx FDS) + EF_FDS_MOD_BIAS (Zxx FDS) +``` diff --git a/docs/0CC-Dn-FT NSF driver update sequence.md b/docs/0CC-Dn-FT NSF driver update sequence.md new file mode 100644 index 00000000..8acdb0f9 --- /dev/null +++ b/docs/0CC-Dn-FT NSF driver update sequence.md @@ -0,0 +1,44 @@ +# 0CC-Dn-FT NSF driver update sequence + +This doc aims to detail the update order as observed in the NSF driver. + +Ideally, the NSF driver should be the de-facto standard in how FT modules should +behave, but since the tracker has desynced in feature parity, this may not be +the case. + +Regardless, this should serve as a reference as to how the driver updates in +sequence. + +``` +ft_music_play + (delay handling) + (tempo handling) + ft_do_row_update + (frame handling) + ft_read_channels (foreach channels do:) + ft_read_pattern + ft_read_note + (switch case pattern command) + (handle volume commands) + (handle instrument commands) + (handle effect commands) + ft_push_echo_buffer + (handle note off) + (handle note release) + (load echo buffer) + ft_push_echo_buffer + (handle note) + ft_read_is_done + ft_skip_row_update (when no updates are available) + (tempo handling) + ft_loop_fx_state + (Sxx handling) + (delayed transpose/release handling) + ft_loop_channels (foreach channels do:) + ft_run_effects (handles the rest of the other effects) + ft_run_instrument + ft_calc_period + (Nxy handling) + ft_update_ (foreach chip do:) + (register writes) +``` \ No newline at end of file diff --git a/docs/Dn-FT DNM format v4_50.md b/docs/Dn-FT DNM format v4_50.md new file mode 100644 index 00000000..a4cc33ee --- /dev/null +++ b/docs/Dn-FT DNM format v4_50.md @@ -0,0 +1,2685 @@ +# Dn-FamiTracker module file (.dnm) format specification (v4.50) + +- Not yet complete! +- Last updated April 20, 2024 + +## About + +- This text aims to document the binary module file format as of Dn-FamiTracker v0.5.0.1. +- Each section is declared sequentially as it appears in the file. +- Unless specified otherwise, all data is stored in **little-endian** format. +- Strings are stored in **ASCII** encoding unless specified otherwise. + +## Format overview + +### Parameters + +- m_iExpansionChip +- m_iChannelsAvailable +- m_iMachine +- m_iEngineSpeed +- m_iVibratoStyle +- m_vHighlight +- m_iNamcoChannels +- m_iSpeedSplitPoint +- m_iDetuneSemitone +- m_iDetuneCent + +### Song Info + +- m_strName +- m_strArtist +- m_strCopyright + +### Tuning + +- m_iDetuneSemitone +- m_iDetuneCent + +### Instruments + +- Instrument index +- Instrument count +- pInstrument + - Type + - CInstrumentManager + - Instrument name length + - Name + +### Sequences + +- 2A03 sequence count + - Sequence index + - Sequence type + - Sequence item count + - Sequence loop point + - Sequence release point + - Settings + - for Sequence item count: + - Value + +### Frames + +- for m_iTrackCount: + - Track frame count + - m_iChannelsAvailable + - Pattern index + - Track default speed + - Track default tempo + - Track default row count (PatternLength) + +### Patterns + +- Pattern track index +- Pattern channel index +- Pattern index +- Pattern data count + - Row index + - stChanNote Note + - Note value + - Octave value + - Instrument index + - Channel volume + - effect columns + - Effect index + - Effect Param + +### DSamples + +- DPCM sample count + - DPCM sample index + - DPCM sample name length + - DPCM sample name + - DPCM sample size + - DPCM sample bytes + +### Header + +- m_iTrackCount + - m_pTracks[i] +- for m_iChannelsAvailable: + - Channel type index (unused) + - for m_iTrackCount: + - Effect column count +- for m_iTrackCount: + - m_vHighlight.First + - m_vHighlight.Second + +### Comments + +- m_bDisplayComment +- m_strComment + +### Sequences VRC6 + +- VRC6 sequence count + - Sequence index + - Sequence type + - Sequence item count + - Sequence loop point + - Sequence release point + - Settings + - for Sequence item count: + - Value + +### Sequences N163 + +- N163 sequence count + - Sequence index + - Sequence type + - Sequence item count + - Sequence loop point + - Sequence release point + - Settings + - for Sequence item count: + - Value + +### Sequences S5B + +- 5B sequence count + - Sequence index + - Sequence type + - Sequence item count + - Sequence loop point + - Sequence release point + - Settings + - for Sequence item count: + - Value + +### Detune Tables + +- Detune table count + - Detune table index + - Detune table note count + - Detune table note index + +### Grooves + +- Groove count + - Groove index + - Groove size + - Groove item +- Use-groove flag count + - Use-groove flag + +### Bookmarks + +- Bookmark Count + - CBookmark, which includes + - Bookmark track index + - Bookmark frame index + - Bookmark row index + - m_vHighlight.First + - m_vHighlight.Second + - m_bPersist + - m_sName + +### Params Extra + +- m_bLinearPitch +- Global semitone tuning +- Global cent tuning + +### JSON + +- (optional JSON data) + - APU1_OFFSET + - APU2_OFFSET + - VRC6_OFFSET + - VRC7_OFFSET + - FDS_OFFSET + - MMC5_OFFSET + - N163_OFFSET + - S5B_OFFSET + - USE_SURVEY_MIX + +### ParamsEmu + +- m_bUseExternalOPLLChips +- for patches: + - m_iOPLLPatchBytes[8] + - m_strOPLLPatchNames + +## Data Types + +- `char` + - Signed 8-bit integer. Used for storing bit flags, strings, and other misc. data. +- `unsigned int` + - Unsigned 32-bit integer. Seems to be only used in `HEADER`? +- `int` + - Signed 32-bit integer. Used for storing numerical data. +- `CInstrument` + - CInstrument class object. + +## Header + +### File Header + +
+ +Data type + + + +Unit size (bytes) + + + +Object name + + + +Typical values + + + +Description + + + +Notes + +
+ +char[256] + + + +Non-padded length of char[] string + + + +`FILE_HEADER_ID` or `FILE_HEADER_ID_DN` + + + +`FamiTracker Module`, `Dn-FamiTracker Module` + + + +Identifier string + + + +In Dn-FT v0.5.0.0, this was changed to `Dn-FamiTracker Module` for non-backwards compatibility of new features. + +
+ +unsigned int + + + +4 + + + +`m_iFileVersion` + + + +0x00000450 + + + +Module version + + + +Version number is formatted as BCD (ex. 4.50) + +
+ +#### Notes + +- Information is based on `DocumentFile.cpp CDocumentFile::BeginDocument()` and `FamiTrackerDoc.cpp CFamiTrackerDoc::SaveDocument()` +- Modules saved in Dn-FamiTracker v0.5.0.0 and later may save modules with `FILE_HEADER_ID_DN` identifiers, to prevent older FamiTracker versions from reading non-backwards compatible data such as `FILE_BLOCK_JSON` and `FILE_BLOCK_PARAMS_EMU`. + +## Block header + +Each block has a 24-byte header consisting of a block ID, block version, and block size. + +
+ +Data type + + + +Unit size (bytes) + + + +Object name + + + +Typical values + + + +Description + + + +Notes + +
+ +char[16] + + + +16 + + + +`m_cBlockID` + + + +`PARAMS` + + + +Identifier string + + + +Length is zero-padded to 16 bytes + +
+ +int + + + +4 + + + +`m_iBlockVersion` + + + +0x00000006 + + + +Block version + + + +Block version number is ANDed with 0xFFFF, but is still written as 32-bit signed integer + +
+ +int + + + +4 + + + +`m_iBlockPointer` + + + +0x1D000000 + + + +Block size, not counting the block header + +
+ +## Internal blocks + +### Parameters block + +Block ID: `PARAMS` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`m_iSongSpeed` + + + +6 + + + +Song speed of track 0 + + + +1 + +
+ +char + + + +1 + + + +`m_iExpansionChip` + + + +0x00 + + + +Expansion audio bitmask + + + +Same format as expansion audio bitmask found in the NSF format + + + +2+ + +
+ +int + + + +4 + + + +`m_iChannelsAvailable` + + + +5 + + + +Number of channels added + + + +Includes the 5 channels from 2A03. + + + +1+ + +
+ +int + + + +4 + + + +`m_iMachine` + + + +0 + + + +NTSC or PAL + + + +1+ + +
+ +int + + + +4 + + + +`m_iPlaybackRateType` + + + +0 + + + +Playback rate type, 0 = default, 1 = custom, 2 = video + + + +7+ + +
+ +int + + + +4 + + + +`m_iPlaybackRate` + + + +16639 + + + +NSF playback rate, in microseconds + + + +7+ + +
+ +int + + + +4 + + + +`m_iEngineSpeed` + + + +60 + + + +Engine refresh rate, in Hz + + + +1-6 + +
+ +int + + + +4 + + + +`m_iVibratoStyle` + + + +1 + + + +0 = old style, 1 = new style + + + +3+ + +
+ +int + + + +4 + + + +? + + + +1 + + + +Hardware sweep pitch reset + + + +Not implemented? Vanilla 0.5b stuff. Probably boolean type. + + + +7+ + +
+ +int + + + +4 + + + +`m_vHighlight.First` + + + +4 + + + +1st row highlight + + + +3-6 + +
+ +int + + + +4 + + + +`m_vHighlight.Second` + + + +16 + + + +2nd row highlight + + + +3-6 + +
+ +int + + + +4 + + + +`m_iNamcoChannels` + + + +8 + + + +Number of N163 channels used + + + +Only written/read when N163 is enabled. + + + +5+ + +
+ +int + + + +4 + + + +`m_iSpeedSplitPoint` + + + +32 + + + +Fxx speed/tempo split-point + + + +6+ + +
+ +char + + + +1 + + + +`m_iDetuneSemitone` + + + +0 + + + +Semitone detuning, range from -12 to 12 + + + +Moved to Tuning block in FT 050B 2020. Also in Extra Parameters block. + + + +8 + +
+ +char + + + +1 + + + +`m_iDetuneCent` + + + +0 + + + +Cent detuning, range from -100 to 100 + + + +Moved to Tuning block in FT 050B 2020. Also in Extra Parameters block. + + + +8 + +
+ +#### Notes + +- Information is based on `CFamiTrackerDoc::WriteBlock_Parameters()` + +### Song Info block + +Block ID: `INFO` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +char[32] + + + +32 + + + +`m_strName` + + + +`(title)` + + + +Module name + + + +Length is zero-padded to 32 bytes + + + +1+ + +
+ +char[32] + + + +32 + + + +`m_strArtist` + + + +`(author)` + + + +Module artist + + + +Length is zero-padded to 32 bytes + + + +1+ + +
+ +char[32] + + + +32 + + + +`m_strCopyright` + + + +`(copyright)` + + + +Module copyright + + + +Length is zero-padded to 32 bytes + + + +1+ + +
+ +#### Notes + +- Information is based on `CFamiTrackerDoc::WriteBlock_SongInfo()` + +### Tuning block + +Block ID: `TUNING` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +char + + + +1 + + + +`m_iDetuneSemitone` + + + +0 + + + +Semitone detuning, range from -12 to 12 + + + +Also in Extra Parameters block. + + + +1+ + +
+ +char + + + +1 + + + +`m_iDetuneCent` + + + +0 + + + +Cent detuning, range from -100 to 100 + + + +Also in Extra Parameters block. + + + +1+ + +
+ +#### Notes + +- Information is based on `CFamiTrackerDoc::WriteBlock_Tuning()` +- Added in FamiTracker 0.5.0 beta 2020 + +### Header block + +Block ID: `HEADER` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +char + + + +1 + + + +`m_iTrackCount` + + + +0x06 + + + +Number of tracks added. + + + +Stores track count - 1. (i.e. `m_iTrackCount` - 1) + + + +2+ + +
+ +char[] + + + +Length of zero-terminated char[] string + + + +Per number of tracks added (`m_iTrackCount`) + + + +`m_pTracks[]->m_sTrackName` + + + +`New song` + + + +Names of each track + + + +Each track name is zero terminated, and therefore delineated by a byte of 0. + + + +3+ + +
+ +char + + + +1 + + + +Per number of channels added (`m_iChannelsAvailable`) + + + +`m_iChannelTypes[]` + + + +`CHANID_SQUARE1` + + + +Channel ID (`enum chan_id_t`) + + + +1+ + +
+ +char[] + + + +Number of tracks added (`m_iTrackCount`) + + + +`m_pTracks[]->m_iEffectColumns[]` + + + +{0x01, 0x02, 0x02, 0x01, 0x01, 0x01, 0x00} + + + +Number of additional effect columns on a given channel, per track + + + +On version 1, this was restricted to the first track. + + + +1+ + +
+ +#### Notes + +- Information is based on `CFamiTrackerDoc::WriteBlock_Header()` + +### Instruments block + +Block ID: `INSTRUMENTS` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`m_pInstrumentManager->GetInstrumentCount()` + + + +23 + + + +Instrument count + + + +Count of existing instruments + + + +1+ + +
+ +int + + + +4 + + + +Per instrument + + + +Instrument index + + + +0 to `MAX_INSTRUMENTS - 1` + + + +Instrument index + + + +1+ + +
+ +char + + + +1 + + + +`m_pInstrumentManager->GetInstrumentCount()->m_iType` + + + +0x01 + + + +Instrument type + + + +1+ + +
+ +CInstrument + + + +size of CInstrument object + + + +`m_pInstrumentManager->GetInstrument()` + + + +(CInstrument object) + + + +Instrument definition + + + +See tables below for instrument definitions + + + +1+ + +
+ +int + + + +4 + + + +`strlen()` of `m_pInstrumentManager->GetInstrument()->GetName()` + + + +10 + + + +Instrument name length + + + +1+ + +
+ +char[] + + + +Instrument name length + + + +`m_pInstrumentManager->GetInstrument()->GetName()` + + + +`bass pluck` + + + +Instrument name + + + +1+ + +
+ +#### Notes + +- If FDS is used then version must be at least 4 or recent files won't load +- v6 adds DPCM delta settings +- This block is only written if any instruments exist + +#### Instrument sequences format + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`SEQ_COUNT` + + + +`enum sequence_t` + + + +Sequence count + + + +Number of defined sequence types. Volume, Arpeggio, Pitch, Hi-Pitch, Duty cycle + + + +1+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSeqInstrument::m_iSeqEnable[]` + + + +1 + + + +0 = sequence is disabled, 1 = sequence is enabled + + + +1+ + +
+ +char + + + +1 + + + +`CSeqInstrument::m_iSeqIndex[]` + + + +2 + + + +Sequence index + + + +1+ + +
+ +##### Notes + +- This format is shared between 2A03, VRC6, N163, and S5B instruments. +- In 0CC-FamiTracker and its forks, this format was converted into a subclass of `CInstrument`, `CSeqInstrument` to deduplicate code. + +#### 2A03 + +Instrument type value: `0x01` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`SEQ_COUNT` + + + +`enum sequence_t` + + + +Sequence count + + + +Volume, Arpeggio, Pitch, Hi-Pitch, Duty / Noise + + + +1+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSeqInstrument::m_iSeqEnable[]` + + + +1 + + + +0 = sequence is disabled, 1 = sequence is enabled + + + +1+ + +
+ +char + + + +1 + + + +`CSeqInstrument::m_iSeqIndex[]` + + + +2 + + + +Sequence index + + + +1+ + +
+ +int + + + +4 + + + +`CInstrument2A03::GetSampleCount()` + + + +5 + + + +DPCM sample count + + + +7+ + +
+ +char + + + +1 + + + +Per note + + + +`Note` + + + +0 to `NOTE_COUNT - 1` + + + +DPCM sample assignment note index + + + +Written only when a sample exists at that note. + + + +7+ + +
+ +char + + + +1 + + + +`CInstrument2A03::m_cSamples[Octave][Note]` + + + +0x00 + + + +DPCM sample assignment index + + + +Written only when a sample exists at that note in version 7+. + + + +1+ + +
+ +char + + + +1 + + + +`CInstrument2A03::m_cSamplePitch[Octave][Note]` + + + +0x00 + + + +DPCM sample pitch of a given note + + + +Written only when a sample exists at that note in version 7+. + + + +1+ + +
+ +char + + + +1 + + + +`CInstrument2A03::m_cSampleDelta[Octave][Note]` + + + +0xFF + + + +DPCM delta offset of a given note + + + +Written only when a sample exists at that note in version 7+. + + + +6+ + +
+ +##### Notes + +- Information is based on `CInstrument2A03::Store()` +- Only 72 notes are defined in version 1. Version 2+ has all 96 notes defined. +- In version 7, the DPCM format has been changed to only count notes with DPCM assignments. + +#### VRC6 + +Instrument type value: `0x02` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`SEQ_COUNT` + + + +5 + + + +Sequence count + + + +Volume, Arpeggio, Pitch, Hi-pitch, Pulse width. + + + +2+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSeqInstrument::m_iSeqEnable[]` + + + +1 + + + +0 = sequence is disabled, 1 = sequence is enabled + + + +2+ + +
+ +char + + + +1 + + + +`CSeqInstrument::m_iSeqIndex[]` + + + +2 + + + +Sequence index + + + +2+ + +
+ +##### Notes + +- Information is based on `CSeqInstrument::Store()` +- Similar to 2A03 instruments but with no special considerations for DPCM + +#### VRC7 + +Instrument type value: `0x03` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`CInstrumentVRC7::m_iPatch` + + + +12 + + + +VRC7 patch number + + + +Hardware patch number of the instrument. + + + +2+ + +
+ +char[8] + + + +8 + + + +`CInstrumentVRC7::m_iRegs[]` + + + +{0x01, 0x21, 0x00, 0x00, 0x00, 0xF0, 0x00, 0x0F} + + + +Custom patch settings + + + +Patch settings of hardware patch 0. + + + +2+ + +
+ +##### Notes + +- Information is based on `CInstrumentVRC7::Store()` + +#### FDS + +Instrument type value: `0x04` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +char[64] + + + +64 + + + +`CInstrumentFDS::m_iSamples[]` + + + +<64 byte sequence of a waveform> + + + +Wave data + + + +3+ + +
+ +char[32] + + + +32 + + + +`CInstrumentFDS::m_iModulation[]` + + + +<32 byte sequence> + + + +Modulation table + + + +3+ + +
+ +int + + + +4 + + + +`CInstrumentFDS::m_iModulationSpeed` + + + +0 + + + +Instrument modulation rate + + + +3+ + +
+ +int + + + +4 + + + +`CInstrumentFDS::m_iModulationDepth` + + + +0 + + + +Instrument modulation depth + + + +3+ + +
+ +int + + + +4 + + + +`CInstrumentFDS::m_iModulationDelay` + + + +0 + + + +Instrument modulation delay + + + +3+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSequence::m_iItemCount` + + + +Sequence length + + + +3+ + +
+ +int + + + +4 + + + +`CSequence::m_iLoopPoint` + + + +Sequence loop point + + + +3+ + +
+ +int + + + +4 + + + +`CSequence::m_iReleasePoint` + + + +Sequence release point + + + +4+ + +
+ +int + + + +4 + + + +`CSequence::m_iSetting` + + + +Sequence setting type + + + +4+ + +
+ +char[] + + + +Sequence length + + + +`CSequence::m_cValues[Index]` + + + +Sequence data + + + +3+ + +
+ +##### Notes + +- Information is based on `CInstrumentFDS::Store()` +- FDS instruments stores its own sequences via `CInstrumentFDS::StoreSequence()`, separate from `CSeqInstrument::Store()` + - These sequences only store the first 3 types + +#### N163 + +Instrument type value: `0x05` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`SEQ_COUNT` + + + +5 + + + +Sequence count + + + +Volume, Arpeggio, Pitch, Hi-pitch, Wave Index. + + + +2+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSeqInstrument::m_iSeqEnable[]` + + + +1 + + + +0 = sequence is disabled, 1 = sequence is enabled + + + +2+ + +
+ +char + + + +1 + + + +`CSeqInstrument::m_iSeqIndex[]` + + + +2 + + + +Sequence index + + + +2+ + +
+ +int + + + +4 + + + +`m_iWaveSize` + + + +32 + + + +Wave data size + + + +2+ + +
+ +int + + + +4 + + + +`m_iWavePos` + + + +0 + + + +Wave data RAM position + + + +Ignored if automatic wave data ram allocation is enabled + + + +2+ + +
+ +int + + + +4 + + + +`m_bAutoWavePos` + + + +0x00 / 0x01 + + + +Automatic wave data RAM allocation + + + +?+ + +
+ +int + + + +4 + + + +`m_iWaveCount` + + + +1 + + + +Wave count + + + +2+ + +
+ +char[] + + + +Wave data size + + + +Per wave count + + + +`m_iSamples[MAX_WAVE_COUNT][MAX_WAVE_SIZE]` + + + +<byte sequence of wave data> + + + +Wave data + + + +2+ + +
+ +##### Notes + +- Information is based on `CInstrumentN163::Store()` +- Automatic wave data RAM allocation feature is from FT 0.5.0 beta + +#### S5B + +Instrument type value: `0x06` + +
+ +Data type + + + +Unit size (bytes) + + + +Repeat + + + +Object name + + + +Typical values + + + +Description + + + +Notes + + + +Present in block version + +
+ +int + + + +4 + + + +`SEQ_COUNT` + + + +5 + + + +Sequence count + + + +Volume, Arpeggio, Pitch, Hi-pitch, Noise / Mode. + + + +2+ + +
+ +char + + + +1 + + + +Per sequence count + + + +`CSeqInstrument::m_iSeqEnable[]` + + + +1 + + + +0 = sequence is disabled, 1 = sequence is enabled + + + +2+ + +
+ +char + + + +1 + + + +`CSeqInstrument::m_iSeqIndex[]` + + + +2 + + + +Sequence index + + + +2+ + +
+ +##### Notes + +- Information is based on `CSeqInstrument::Store()` +- Similar to 2A03 instruments but with no special considerations for DPCM +### Sequences block + +### Frames block + +### Patterns block + +### DPCM Samples block + +### Comments block + +## Expansion blocks + +### VRC6 Sequences block + +### N163 Sequences block + +### S5B Sequences block + +## 0CC-FamiTracker extension blocks + +### Extra Parameters block + +### Detune Tables block + +### Grooves block + +### Bookmarks block + +## Dn-FamiTracker extension blocks + +### JSON block + +### Emulation Parameters block diff --git a/docs/Dn-FT JSON block format v1_1.md b/docs/Dn-FT JSON block format v1_1.md new file mode 100644 index 00000000..f6fdf5e7 --- /dev/null +++ b/docs/Dn-FT JSON block format v1_1.md @@ -0,0 +1,24 @@ +# Dn-FT JSON block format version 1.1 +Must always be backwards compatible using a never remove, only add strategy. + +Listed below are all the recognized keywords, with their default values. + +**JSON data is only for optional settings, do not add any tracker or emulator crucial data here!** + +```JSON +{ + // Device mixing offsets, described in centibels. too late to change to millibels. + // range is +- 12 db. + "apu1-offset": 0, + "apu2-offset": 0, + "fds-offset": 0, + "mmc5-offset": 0, + "n163-offset": 0, + "s5b-offset": 0, + "vrc6-offset": 0, + "vrc7-offset": 0, + + // Use better mixing values derived from survey: https://forums.nesdev.org/viewtopic.php?f=2&t=17741 + "use-survey-mix": false +} +``` \ No newline at end of file diff --git a/docs/How to add a chip.md b/docs/How to add a chip.md new file mode 100644 index 00000000..79d2e528 --- /dev/null +++ b/docs/How to add a chip.md @@ -0,0 +1,23 @@ +# How to add a Chip + +This doc aims to detail how to add a custom chip to Dn-FT, should the +NSF/NSFe/NSF2/INES/INES2.0 update to add new expansion audio. + +## Disclaimer + +Dn-FamiTracker's aim is to fill in the gaps of NSF, NSFe and NSF2 features and/or emerging NESDev homebrew standards that 0CC or Vanilla fails to meet due to a lack of maintenance. + +As such, Dn-FT will only implement features present in current NSF/NSFe/NSF2/INES/INES2.0 standards and definitions, keeping in mind the original goal of producing music for the NES/Famicom systems. + +If you want to add different chips from different systems/formats, please direct your requests/efforts to [Furnace](https://github.com/tildearrow/furnace). + + +## 1. All of these **must be implemented in one go** before you can have a chance to prototype and debug: +1. Emulation core and emu core class handler. eg. `EPSM.cpp`; `emu_YMF288.cpp` +1. sound handling and mixing (eg. `APU.cpp`, `Mixer.cpp`, `SoundGen.cpp` implementations) +1. Channel handler (eg. `ChannelsEPSM.cpp`, `ChannelHandler.cpp`) +1. Instrument handling (eg. `InstrumentEPSM.cpp`, `InstrumentHandlerEPSM.cpp`, `InstrumentEditorEPSM.cpp`, `SeqInstHandlerEPSM.cpp`) +1. Document bindings and types (eg. `APU\Types.h`, `ChannelFactory.cpp`, `ChannelMap.cpp`, `ChannelsDlg.cpp`, `DetuneDlg.cpp`, `FamiTrackerDoc.cpp`, `FamiTrackerTypes.cpp`, `FamiTrackerView.cpp`, `TrackerChannel.cpp`) + +## 2. After prototyping and debugging and making sure everything works okay, be sure to implement the NSF driver +1. (see [bhop](https://github.com/zeta0134/bhop)) \ No newline at end of file diff --git a/docs/Tracker player update sequence.md b/docs/Tracker player update sequence.md new file mode 100644 index 00000000..393df0a1 --- /dev/null +++ b/docs/Tracker player update sequence.md @@ -0,0 +1,57 @@ +# Tracker player update sequence + +Documents the update sequence of the player in the tracker. +```cpp +CSoundGen::PlayChannelNotes(); + CSoundGen::PlayNote(); + CSoundGen::EvaluateGlobalEffects(); + CChannelHandler::HandleDelay(); + CChannelHandler::HandleNoteData(); + // (handle echo buffer) + CChannelHandler::WriteEchoBuffer(); + // (clear note cut and note release) + // (handle effects) + CChannelHandler::HandleEffect(); + // (handle volume command and Nxy) + // (handle instrument command) + switch (pNoteData->Note) { + case NONE: + HandleEmptyNote(); + break; + case HALT: + m_bRelease = false; + HandleCut(); + break; + case RELEASE: + HandleRelease(); + break; + default: + HandleNote(pNoteData->Note, pNoteData->Octave); + break; + } + // (handle note slide) + if (new_instrument || note_trigger) + CChannelHandler::HandleInstrument(); + if (new_instrument) + m_pInstHandler->LoadInstrument(pInstrument); + if (note_trigger) + m_pInstHandler->TriggerInstrument(); +CSoundGen::UpdatePlayer(); +CSoundGen::UpdateChannels(); // run instruments, effects, etc. + CChannelHandler::ProcessChannel(); + UpdateDelay(); + UpdateNoteCut(); + UpdateNoteRelease(); + UpdateNoteVolume(); // // // + UpdateTranspose(); // // // + if (m_iVolSlideTarget < 0) // // !! + UpdateVolumeSlide(); + else + UpdateTargetVolumeSlide(); + UpdateVibratoTremolo(); + UpdateEffects(); + if (m_pInstHandler) m_pInstHandler->UpdateInstrument(); // // // +CSoundGen::UpdateAPU(); // write to registers + // this function also happens to blit the current audio buffer + // to either the wave output or the sound driver +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..6d8975f1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +# Welcome to the Dn-FamiTracker wiki docs! + +TODO: add code documentation and specific tutorials here to help new and coming contributers \ No newline at end of file diff --git a/docs/resources/Dn-FT app icon.png b/docs/resources/Dn-FT app icon.png new file mode 100644 index 00000000..ae9c5c57 Binary files /dev/null and b/docs/resources/Dn-FT app icon.png differ