Skip to content

Commit f291d67

Browse files
Gumball2415Gumball2415
authoredJan 11, 2025··
Merge pull request #319 from Dn-Programming-Core-Management/docs-license-ver-meta-dev
Update docs and port from GitHub Wiki
·
log-wav-export-debugDn0.5.1.1
2 parents 6ee0043 + c8f2cda commit f291d67

11 files changed

+804
-8
lines changed
 

‎docs/0CC vs FT effects type order.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 0CC vs FT effect type order
2+
3+
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.
4+
5+
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).
6+
7+
For devs: please increment PATTERNS block version immediately.
8+
9+
```
10+
After EF_SUNSOFT_ENV_LO (Jxx S5B),
11+
FT order:
12+
EF_NOTE_RELEASE (Lxx)
13+
EF_GROOVE (Oxx)
14+
EF_TRANSPOSE (Txy)
15+
EF_N163_WAVE_BUFFER (Zxx N163)
16+
EF_FDS_VOLUME (Exx FDS)
17+
EF_FDS_MOD_BIAS (Zxx FDS)
18+
EF_SUNSOFT_NOISE (Wxx S5B)
19+
EF_VRC7_PORT (Hxx VRC7)
20+
EF_VRC7_WRITE (Ixx VRC7)
21+
22+
0CC order:
23+
EF_SUNSOFT_NOISE (Wxx S5B)
24+
EF_VRC7_PORT (Hxx VRC7)
25+
EF_VRC7_WRITE (Ixx VRC7)
26+
EF_NOTE_RELEASE (Lxx)
27+
EF_GROOVE (Oxx)
28+
EF_TRANSPOSE (Txy)
29+
EF_N163_WAVE_BUFFER (Zxx N163)
30+
EF_FDS_VOLUME (Exx FDS)
31+
EF_FDS_MOD_BIAS (Zxx FDS)
32+
```

‎docs/0CC-Dn-FT NSF driver update sequence.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# 0CC-Dn-FT NSF driver update sequence
2+
3+
This doc aims to detail the update order as observed in the NSF driver.
4+
5+
Ideally, the NSF driver should be the de-facto standard in how FT modules should
6+
behave, but since the tracker has desynced in feature parity, this may not be
7+
the case.
8+
9+
Regardless, this should serve as a reference as to how the driver updates in
10+
sequence.
11+
12+
```
13+
ft_music_play
14+
(delay handling)
15+
(tempo handling)
16+
ft_do_row_update
17+
(frame handling)
18+
ft_read_channels (foreach channels do:)
19+
ft_read_pattern
20+
ft_read_note
21+
(switch case pattern command)
22+
(handle volume commands)
23+
(handle instrument commands)
24+
(handle effect commands)
25+
ft_push_echo_buffer
26+
(handle note off)
27+
(handle note release)
28+
(load echo buffer)
29+
ft_push_echo_buffer
30+
(handle note)
31+
ft_read_is_done
32+
ft_skip_row_update (when no updates are available)
33+
(tempo handling)
34+
ft_loop_fx_state
35+
(Sxx handling)
36+
(delayed transpose/release handling)
37+
ft_loop_channels (foreach channels do:)
38+
ft_run_effects (handles the rest of the other effects)
39+
ft_run_instrument
40+
ft_calc_period
41+
(Nxy handling)
42+
ft_update_<chip> (foreach chip do:)
43+
(register writes)
44+
```

‎docs/CONTRIBUTING.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,17 @@ Welcome! Thank you for considering to contribute to Dn-FamiTracker. We really ne
1212

1313
## Git guidelines
1414

15-
- Write pull requests that passes CI builds.
16-
- Make sure to adhere to the [pull request template](pull_request_template.md) message guidelines.
15+
- Write pull requests that passes CI builds and tests.
16+
- Make sure to adhere to the [pull request template](Dn-FamiTracker/docs/pull_request_template.md) message guidelines.
1717
- Base your pull request on the `main` branch.
18-
- If a merge conflict happens due to not being updated in a long time, resolve merge conflicts and rebase your pull request to the latest reasonable version of the `main` branch.
18+
- If a merge conflict happens due to not being updated in a long time, resolve merge conflicts and rebase your pull request to the latest compatible version of the `main` branch.
19+
- Be sure to update [Dn-Help](https://github.com/Dn-Programming-Core-Management/Dn-help) on your pull request as needed.
20+
- Create a corresponding pull request on Dn-help that links to your main pull request.
1921

2022
### For Dn-FT maintainers:
2123

22-
- Do **NOT** push directly to the `main` branch. Instead, push your changes to these branches first before writing a pull request:
24+
- Do **NOT** push directly to the `main` branch. Instead, push your changes to a branch first before writing a pull request.
25+
- These branches are designated to be reoccurring may be used for the following:
2326
- `app-emu-module-nsf_driver-dev`
2427
- This branch is for modifying the application itself, such as the NSF driver, the module format, loading and saving code, emulator core, audio drivers, etc.
2528
- `docs-license-ver-meta-dev`
@@ -29,7 +32,7 @@ Welcome! Thank you for considering to contribute to Dn-FamiTracker. We really ne
2932
- You will most likely force push this branch to hell and back, so be sure to do it on your own GitHub user's fork.
3033
- Other branches may be made for more niche/specific modifications and fixes.
3134
- If your pull request touches two or more of these categories, it's fine but please keep it minimal.
32-
- Otherwise, create a new branch as mentioned previously.
35+
- Otherwise, create a new branch.
3336

3437
## Dependencies and Building
3538

@@ -64,5 +67,7 @@ To edit and/or build the source, you may use Visual Studio 2022, or alternativel
6467

6568
## Important Things to Note
6669

67-
- When committing changes, **file extension case must be the same as the original file!** This might result in merge conflicts, because Git is case sensitive, but in Windows systems, the file system is case insensitive by default.
68-
- Additionally, case sensitivity in Windows can be enabled through WSL, but it **must only be enabled to resolve merge conflicts regarding file extension case sensitivity**. If case sensitivity is left enabled, Visual Studio throws a bunch of errors due to the way IntelliSense capitalizes paths internally.
70+
- When committing changes, ***file extension case must be the same as the original file!***
71+
- This might result in merge conflicts, because Git is case sensitive, but in Windows systems, the file system is case insensitive by default.
72+
- Additionally, case sensitivity in Windows can be enabled through WSL, but it **must only be enabled to resolve merge conflicts regarding file extension case sensitivity**.
73+
- If case sensitivity is left enabled, Visual Studio throws a lot of errors due to the way IntelliSense capitalizes paths internally.

‎docs/Dn-FT JSON block format v1_1.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dn-FT JSON block format version 1.1
2+
Must always be backwards compatible using a never remove, only add strategy.
3+
4+
Listed below are all the recognized keywords, with their default values.
5+
6+
**JSON data is only for optional settings, do not add any tracker or emulator crucial data here!**
7+
8+
```JSON
9+
{
10+
// Device mixing offsets, described in centibels. too late to change to millibels.
11+
// range is +- 12 db.
12+
"apu1-offset": 0,
13+
"apu2-offset": 0,
14+
"fds-offset": 0,
15+
"mmc5-offset": 0,
16+
"n163-offset": 0,
17+
"s5b-offset": 0,
18+
"vrc6-offset": 0,
19+
"vrc7-offset": 0,
20+
21+
// Use better mixing values derived from survey: https://forums.nesdev.org/viewtopic.php?f=2&t=17741
22+
"use-survey-mix": false
23+
}
24+
```

‎docs/Dn-FT instrument format.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Dn-FamiTracker Instrument format
2+
3+
- Document updated 2025-01-06
4+
- Version 2.4
5+
6+
---
7+
8+
## File header
9+
10+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid values_ | _Notes_ |
11+
| ------------ | ---------------------- | -------- | ---------------------------------------------------------------- | ---------------------- | ---------------------------------- | ---------------------- |
12+
| char[4] | 4 | | `INST_HEADER` | Identifier string | `FTI` | Null-terminated string |
13+
| unsigned int | 4 | | `INST_VERSION` | Module version | `2.4` | Null-terminated string |
14+
| char | 1 | | `m_pInstrumentManager->GetInstrument()->m_iType` | Instrument type | `enum inst_type_t` | See table. |
15+
| int | 4 | | `strlen()` of `m_pInstrumentManager->GetInstrument()->GetName()` | Instrument name length | 0 to `CInstrument::INST_NAME_MAX`. | |
16+
| char[] | Instrument name length | | `m_pInstrumentManager->GetInstrument()->GetName()` | Instrument name | | |
17+
18+
## Instrument type value
19+
20+
| *Chip* | *Index* |
21+
| ---- | ----- |
22+
| 2A03 | 0x01 |
23+
| VRC6 | 0x02 |
24+
| VRC7 | 0x03 |
25+
| FDS | 0x04 |
26+
| N163 | 0x05 |
27+
| S5B | 0x06 |
28+
29+
## Base instrument format
30+
31+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
32+
| ----------- | ------------------- | ------------------ | ---------------------------------- | ------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------ | -------------------------- |
33+
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Number of defined sequence types. <br>Volume, Arpeggio, Pitch, Hi-Pitch, Duty cycle | 1+ |
34+
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
35+
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |
36+
37+
### 2A03 instruments
38+
39+
Instrument type value: `0x01`
40+
41+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
42+
| ----------- | ------------------- | ---------------------------- | ----------------------------------------------- | ------------------------------------------------- | --------------------- | ------------------------------------------------------------ | -------------------------- |
43+
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Volume, Arpeggio, Pitch, Hi-Pitch, Duty / Noise | 1+ |
44+
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
45+
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |
46+
| int | 4 | | `CInstrument2A03::GetSampleCount()` | DPCM sample assignment count | 0 to `MAX_DSAMPLES` | | 7+ |
47+
| 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+ |
48+
| 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+ |
49+
| 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+ |
50+
| 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+ |
51+
#### Notes
52+
53+
- Information is based on `CInstrument2A03::Store()`
54+
- Only 72 notes are defined in version 1. Version 2+ has all 96 notes defined.
55+
- In FamiTracker 0.5.0 beta, the DPCM format has been changed to only count notes with DPCM assignments.
56+
57+
### VRC6 instruments
58+
59+
- Same format as base instrument sequences format.
60+
- Fifth sequence type is named `Pulse Width`.
61+
62+
#### Notes
63+
64+
- Information is based on `CSeqInstrument::Store()`
65+
- Similar to 2A03 instruments but with no special considerations for DPCM
66+
67+
### VRC7 instruments
68+
69+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
70+
| ----------- | ------------------- | -------- | ---------------------------------- | --------------------- | ------------- | ---------------------------------------- | -------------------------- |
71+
| int | 4 | | `CInstrumentVRC7::m_iPatch` | VRC7 patch number | | Hardware patch number of the instrument. | 2+ |
72+
| char[8] | 8 | | `CInstrumentVRC7::m_iRegs[]` | Custom patch settings | | Patch settings of hardware patch 0. | 2+ |
73+
74+
#### Notes
75+
76+
- Information is based on `CInstrumentVRC7::Store()`
77+
78+
### FDS instruments
79+
80+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
81+
| ----------- | ------------------- | -------------------------------- | ------------------------------------ | --------------------------- | ------------------- | ------- | -------------------------- |
82+
| char[64] | 64 | | `CInstrumentFDS::m_iSamples[]` | Wave data | | | 3+ |
83+
| char[32] | 32 | | `CInstrumentFDS::m_iModulation[]` | Modulation table | | | 3+ |
84+
| int | 4 | | `CInstrumentFDS::m_iModulationSpeed` | Instrument modulation rate | | | 3+ |
85+
| int | 4 | | `CInstrumentFDS::m_iModulationDepth` | Instrument modulation depth | | | 3+ |
86+
| int | 4 | | `CInstrumentFDS::m_iModulationDelay` | Instrument modulation delay | | | 3+ |
87+
| char | 1 | `CInstrumentFDS::SEQUENCE_COUNT` | `CSequence::m_iItemCount` | Sequence item count | 0 to 255 | | 3+ |
88+
| int | 4 | ^ | `CSequence::m_iLoopPoint` | Sequence loop point | -1 to`SeqCount - 1` | | 3+ |
89+
| int | 4 | ^ | `CSequence::m_iReleasePoint` | Sequence release point | -1 to`SeqCount - 1` | | 4+ |
90+
| int | 4 | ^ | `CSequence::m_iSetting` | Sequence setting type | `seq_setting_t` | | 4+ |
91+
| char[] | Sequence item count | ^ | `CSequence::m_cValues[Index]` | Sequence data | | | 3+ |
92+
93+
#### Notes
94+
95+
- Information is based on `CInstrumentFDS::Store()`
96+
- FDS instruments stores its own sequences via `CInstrumentFDS::StoreSequence()`, separate from `CSeqInstrument::Store()`
97+
- These sequences only store 3 types, Volume, Arpeggio, and Pitch.
98+
- In version 3, volume range was 0-15. Later versions have volume ranges from 0-31.
99+
- In version 2, FDS sequences were stored incorrectly.
100+
101+
### N163 instruments
102+
103+
| _Data type_ | _Unit size (bytes)_ | _Repeat_ | _Object/relevant variable in code_ | _Description_ | _Valid range_ | _Notes_ | _Present in block version_ |
104+
| ----------- | ------------------- | ------------------ | ------------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | -------------------------- |
105+
| int | 4 | | `SEQ_COUNT` | Sequence count | `enum sequence_t` | Number of defined sequence types. <br>Volume, Arpeggio, Pitch, Hi-Pitch, Duty cycle | 1+ |
106+
| char | 1 | Per sequence count | `CSeqInstrument::m_iSeqEnable[]` | 0 = sequence is disabled, 1 = sequence is enabled | `enum sequence_t` | | 1+ |
107+
| char | 1 | ^ | `CSeqInstrument::m_iSeqIndex[]` | Sequence index | `enum sequence_t` | | 1+ |
108+
| int | 4 | | `AutoPosition` | Automatic wave data RAM allocation | 0, nonzero | | 8+ |
109+
| 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 |
110+
| int | 4 | | `m_iWavePos` | N163 wave position | 0 to `MAX_WAVE_SIZE - 1` | Ignored if automatic wave data ram allocation is enabled | 2-6 |
111+
| int | 4 | | `m_iWaveCount` | N163 wave count | 1 to `MAX_WAVE_COUNT` | | 2+ |
112+
| char[] | Wave data size | Per wave count | `m_iSamples[MAX_WAVE_COUNT][MAX_WAVE_SIZE]` | N163 wave sample | 0 to 15 | | 2+ |
113+
114+
#### Notes
115+
116+
- Information is based on `CInstrumentN163::Store()` and instrument file binary analysis
117+
- Automatic wave data RAM allocation feature is from FT 0.5.0 beta.
118+
119+
### S5B instruments
120+
121+
- Same format as base instrument sequences format.
122+
- Fifth sequence type is named `Noise / Mode`.
123+
124+
#### Notes
125+
126+
- Information is based on `CSeqInstrument::Store()`
127+
- Similar to 2A03 instruments but with no special considerations for DPCM

‎docs/Dn-FT module format.md‎

Lines changed: 481 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/How to add a chip.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# How to add a Chip
2+
3+
This doc aims to detail how to add a custom chip to Dn-FT, should the
4+
NSF/NSFe/NSF2/INES/INES2.0 update to add new expansion audio.
5+
6+
## Disclaimer
7+
8+
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.
9+
10+
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.
11+
12+
If you want to add different chips from different systems/formats, please direct your requests/efforts to [Furnace](https://github.com/tildearrow/furnace).
13+
14+
15+
## 1. All of these **must be implemented in one go** before you can have a chance to prototype and debug:
16+
1. Emulation core and emu core class handler. eg. `EPSM.cpp`; `emu_YMF288.cpp`
17+
1. sound handling and mixing (eg. `APU.cpp`, `Mixer.cpp`, `SoundGen.cpp` implementations)
18+
1. Channel handler (eg. `ChannelsEPSM.cpp`, `ChannelHandler.cpp`)
19+
1. Instrument handling (eg. `InstrumentEPSM.cpp`, `InstrumentHandlerEPSM.cpp`, `InstrumentEditorEPSM.cpp`, `SeqInstHandlerEPSM.cpp`)
20+
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`)
21+
22+
## 2. After prototyping and debugging and making sure everything works okay, be sure to implement the NSF driver
23+
1. (see [bhop](https://github.com/zeta0134/bhop))

‎docs/Tracker player update sequence.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Tracker player update sequence
2+
3+
Documents the update sequence of the player in the tracker.
4+
```cpp
5+
CSoundGen::PlayChannelNotes();
6+
CSoundGen::PlayNote();
7+
CSoundGen::EvaluateGlobalEffects();
8+
CChannelHandler::HandleDelay();
9+
CChannelHandler::HandleNoteData();
10+
// (handle echo buffer)
11+
CChannelHandler::WriteEchoBuffer();
12+
// (clear note cut and note release)
13+
// (handle effects)
14+
CChannelHandler::HandleEffect();
15+
// (handle volume command and Nxy)
16+
// (handle instrument command)
17+
switch (pNoteData->Note) {
18+
case NONE:
19+
HandleEmptyNote();
20+
break;
21+
case HALT:
22+
m_bRelease = false;
23+
HandleCut();
24+
break;
25+
case RELEASE:
26+
HandleRelease();
27+
break;
28+
default:
29+
HandleNote(pNoteData->Note, pNoteData->Octave);
30+
break;
31+
}
32+
// (handle note slide)
33+
if (new_instrument || note_trigger)
34+
CChannelHandler::HandleInstrument();
35+
if (new_instrument)
36+
m_pInstHandler->LoadInstrument(pInstrument);
37+
if (note_trigger)
38+
m_pInstHandler->TriggerInstrument();
39+
CSoundGen::UpdatePlayer();
40+
CSoundGen::UpdateChannels(); // run instruments, effects, etc.
41+
CChannelHandler::ProcessChannel();
42+
UpdateDelay();
43+
UpdateNoteCut();
44+
UpdateNoteRelease();
45+
UpdateNoteVolume(); // // //
46+
UpdateTranspose(); // // //
47+
if (m_iVolSlideTarget < 0) // // !!
48+
UpdateVolumeSlide();
49+
else
50+
UpdateTargetVolumeSlide();
51+
UpdateVibratoTremolo();
52+
UpdateEffects();
53+
if (m_pInstHandler) m_pInstHandler->UpdateInstrument(); // // //
54+
CSoundGen::UpdateAPU(); // write to registers
55+
// this function also happens to blit the current audio buffer
56+
// to either the wave output or the sound driver
57+
```

‎docs/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Welcome to the Dn-FamiTracker wiki docs!
2+
3+
TODO: add code documentation and specific tutorials here to help new and coming contributers

‎docs/pull_request_template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ This pull request aims to `(specify reason)`.
44

55
### Changes in this PR:
66

7-
- (cite all changes made in the PR for change log)
7+
- (cite all changes made in the PR for change log)
88
- Fixes/addresses issue `#<issue number>`.

‎docs/resources/Dn-FT app icon.png‎

1.13 MB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.