Skip to content

Commit

Permalink
Port GitHub wiki pages to repo markdown files
Browse files Browse the repository at this point in the history 
- Update module and instrument docs
  • Loading branch information
@Gumball2415
Gumball2415 committed Jan 10, 2025
1 parent a9cbf00 commit aa84ae0
Show file tree
Hide file tree
Showing 9 changed files with 791 additions and 0 deletions.
32 changes: 32 additions & 0 deletions docs/0CC vs FT effects type order.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# 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).

For devs: please increment PATTERNS block version immediately.

```
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)
```
44 changes: 44 additions & 0 deletions docs/0CC-Dn-FT NSF driver update sequence.md
View file
Original file line number Diff line number Diff line change
@@ -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_<chip> (foreach chip do:)
(register writes)
```
24 changes: 24 additions & 0 deletions docs/Dn-FT JSON block format v1_1.md
View file
Original file line number Diff line number Diff line change
@@ -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
}
```
127 changes: 127 additions & 0 deletions docs/Dn-FT instrument format.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Dn-FamiTracker Instrument format

- Document updated 2025-01-06
- Version 2.4

---

## File header

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid values_ | _Notes_ |
| ------------ | ---------------------- | -------- | ---------------------------------------------------------------- | ---------------------- | ---------------------------------- | ---------------------- |
| char[4] | 4 | | `INST_HEADER` | Identifier string | `FTI` | Null-terminated string |
| unsigned int | 4 | | `INST_VERSION` | Module version | `2.4` | Null-terminated string |
| char | 1 | | `m_pInstrumentManager->GetInstrument()->m_iType` | Instrument type | `enum inst_type_t` | See table. |
| int | 4 | | `strlen()` of `m_pInstrumentManager->GetInstrument()->GetName()` | Instrument name length | 0 to `CInstrument::INST_NAME_MAX`. | |
| char[] | Instrument name length | | `m_pInstrumentManager->GetInstrument()->GetName()` | Instrument name | | |

## Instrument type value

| *Chip* | *Index* |
| ---- | ----- |
| 2A03 | 0x01 |
| VRC6 | 0x02 |
| VRC7 | 0x03 |
| FDS | 0x04 |
| N163 | 0x05 |
| S5B | 0x06 |

## Base instrument format

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
| ----------- | ------------------- | ------------------ | ---------------------------------- | ------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------ | -------------------------- |
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Number of defined sequence types. <br>Volume, Arpeggio, Pitch, Hi-Pitch, Duty cycle | 1+ |
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |

### 2A03 instruments

Instrument type value: `0x01`

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
| ----------- | ------------------- | ---------------------------- | ----------------------------------------------- | ------------------------------------------------- | --------------------- | ------------------------------------------------------------ | -------------------------- |
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Volume, Arpeggio, Pitch, Hi-Pitch, Duty / Noise | 1+ |
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |
| int | 4 | | `CInstrument2A03::GetSampleCount()` | DPCM sample assignment count | 0 to `MAX_DSAMPLES` | | 7+ |
| char | 1 | DPCM sample assignment count | `Note` | DPCM sample assignment note index | 0 to `NOTE_COUNT - 1` | Written only when a sample exists at that note. | 7+ |
| char | 1 | ^ | `CInstrument2A03::m_cSamples[Octave][Note]` | DPCM sample assignment index | 0 to `MAX_DSAMPLES` | Written only when a sample exists at that note in FT 050b1+. | 1+ |
| char | 1 | ^ | `CInstrument2A03::m_cSamplePitch[Octave][Note]` | DPCM sample pitch | 0x0 to 0xF | Written only when a sample exists at that note in FT 050b1+. | 1+ |
| char | 1 | ^ | `CInstrument2A03::m_cSampleDelta[Octave][Note]` | DPCM delta offset of a given note | | Written only when a sample exists at that note in FT 050b1+. | 6+ |
#### Notes

- Information is based on `CInstrument2A03::Store()`
- Only 72 notes are defined in version 1. Version 2+ has all 96 notes defined.
- In FamiTracker 0.5.0 beta, the DPCM format has been changed to only count notes with DPCM assignments.

### VRC6 instruments

- Same format as base instrument sequences format.
- Fifth sequence type is named `Pulse Width`.

#### Notes

- Information is based on `CSeqInstrument::Store()`
- Similar to 2A03 instruments but with no special considerations for DPCM

### VRC7 instruments

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
| ----------- | ------------------- | -------- | ---------------------------------- | --------------------- | ------------- | ---------------------------------------- | -------------------------- |
| int | 4 | | `CInstrumentVRC7::m_iPatch` | VRC7 patch number | | Hardware patch number of the instrument. | 2+ |
| char[8] | 8 | | `CInstrumentVRC7::m_iRegs[]` | Custom patch settings | | Patch settings of hardware patch 0. | 2+ |

#### Notes

- Information is based on `CInstrumentVRC7::Store()`

### FDS instruments

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
| ----------- | ------------------- | -------------------------------- | ------------------------------------ | --------------------------- | ------------------- | ------- | -------------------------- |
| char[64] | 64 | | `CInstrumentFDS::m_iSamples[]` | Wave data | | | 3+ |
| char[32] | 32 | | `CInstrumentFDS::m_iModulation[]` | Modulation table | | | 3+ |
| int | 4 | | `CInstrumentFDS::m_iModulationSpeed` | Instrument modulation rate | | | 3+ |
| int | 4 | | `CInstrumentFDS::m_iModulationDepth` | Instrument modulation depth | | | 3+ |
| int | 4 | | `CInstrumentFDS::m_iModulationDelay` | Instrument modulation delay | | | 3+ |
| char | 1 | `CInstrumentFDS::SEQUENCE_COUNT` | `CSequence::m_iItemCount` | Sequence item count | 0 to 255 | | 3+ |
| int | 4 | ^ | `CSequence::m_iLoopPoint` | Sequence loop point | -1 to`SeqCount - 1` | | 3+ |
| int | 4 | ^ | `CSequence::m_iReleasePoint` | Sequence release point | -1 to`SeqCount - 1` | | 4+ |
| int | 4 | ^ | `CSequence::m_iSetting` | Sequence setting type | `seq_setting_t` | | 4+ |
| char[] | Sequence item count | ^ | `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 3 types, Volume, Arpeggio, and Pitch.
- In version 3, volume range was 0-15. Later versions have volume ranges from 0-31.
- In version 2, FDS sequences were stored incorrectly.

### N163 instruments

| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
| ----------- | ------------------- | ------------------ | ------------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | -------------------------- |
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Number of defined sequence types. <br>Volume, Arpeggio, Pitch, Hi-Pitch, Duty cycle | 1+ |
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |
| int | 4 | | `AutoPosition` | Automatic wave data RAM allocation | 0, nonzero | | 8+ |
| int | 4 | | `m_iWaveSize` | N163 wave size | 4 to `MAX_WAVE_SIZE` | In FT 0.5.0 beta, `m_iWaveSize` is determined by `m_iWaveCount / remaining_bytes` | 2-6 |
| int | 4 | | `m_iWavePos` | N163 wave position | 0 to `MAX_WAVE_SIZE - 1` | Ignored if automatic wave data ram allocation is enabled | 2-6 |
| int | 4 | | `m_iWaveCount` | N163 wave count | 1 to `MAX_WAVE_COUNT` | | 2+ |
| char[] | Wave data size | Per wave count | `m_iSamples[MAX_WAVE_COUNT][MAX_WAVE_SIZE]` | N163 wave sample | 0 to 15 | | 2+ |

#### Notes

- Information is based on `CInstrumentN163::Store()` and instrument file binary analysis
- Automatic wave data RAM allocation feature is from FT 0.5.0 beta.

### S5B instruments

- Same format as base instrument sequences format.
- Fifth sequence type is named `Noise / Mode`.

#### Notes

- Information is based on `CSeqInstrument::Store()`
- Similar to 2A03 instruments but with no special considerations for DPCM
Loading

0 comments on commit aa84ae0

Please sign in to comment.