Farandole .F3R blocked linear module format (1.0)
by Daniel Potter/Digital Infinity

  *NOTE* THIS FILE IS VERY TENTATIVE. IDEAS OR COMMENTS ARE *VERY* WELCOME!
  HELP US CREATE THE MOST AWESOME FORMAT EVER FOR THE MOST AWESOME TRACKER
               EVER (maybe not yet, but it will be, i promise)

The methodology behind the F3R format is that every section is headed by a
4 byte header telling what section follows, and a 4 byte dword in standard
Intel format telling the length of that section. This allows the program to
skip over any section it does not recognize, and allows storage of external
thingies in the file, for whatever purpose you see fit.

Length of the section does NOT include the length of the header magic or the
length field. So if you want that, you must add 8 bytes. Here's a list of
all the sections:

HEAD   - Header section - includes info about the song
FARV   - Farandole variables - only here if created with Farandole, and only
         if saved in full (not stripped) format. The FARV section stores
         info the composer needs to completely restore the state of the
         tracker. Otherwise you will be placed on patt 0, row 0, chan 0, etc.
SAMP   - Sample list+sample data
PATT   - Order list+Pattern data
STXT   - Songtext in ASCII format
SANS   - Songtext in ANSI format - no animations
APIC   - Author picture.

Other sections are mostly program specific, and should be skipped over unless
you know what they are, or if you created them yourself. Obviously it would
be very easy to make a program to add sections to the file since it is not
neccessarily in any order (except that the HEAD section is always first).

Here's a list of all the sections:

PREFIX (note this section is NOT preceeded by a description or length)
------

len             description
---             -----------
 3              F3R file magic ('F3R')
 3              Composer magic. Usually 'FAR' (Farandole)
 32             Song name in ASCIIZ

HEAD
----

len             description
---             -----------
 1              Song version. Current version is 0x10 (1.0)
 1              Number of channels. Up to 256, but usually no more than 16.
 1              Song TPS (ticks per sec). 50 for MOD's, 32 for FAR's and
                669's.
 NChan          Default panning for each channel (0-F)

FARV (taken from FORMATS.DOC in Farandole)
----

len      description
---      -----------
 16      Channel ON/OFF map
 1       Current editing octave
 1       Current editing voice
 1       Current editing row
 1       Current editing pattern
 1       Current editing order
 1       Current editing sample
 1       Current editing volume
 1       Current top of screen display (top row visible)
 1       Current editing area of the screen (0=sample,1=pattern,2=order)
 1       Current tempo (default tempo)
 1       MarkTop (block)
 1       MarkBot (block)
 1       Grid granularity (default 4)
 1       Edit Mode

SAMP
----

len               description
---               -----------
 1                Number of samples. Obviously 0-FF.

Repeated for NOS:

len               description
---               -----------
 32               Name of sample
 4                Length of sample
 1                FineTune value (+/- on the GUS period value*2 for 16 chnls):
                  GUS_PERIOD+(FT*2)
 1                Max Volume
 4                Repeat start
 4                Repeat end - If the sample is looping, this should be set
                  to the repeat end value. Otherwise, it should be set to the
                  length of the sample.
 1                Sample type byte

   1<<0    8/16 bit (8=0 16=1)

 1                Looping mode byte
   1<<3    Looped=1 NotLooped=0
 (len)            Sample data in raw SIGNED format


PATT
----

len             description
---             -----------
 1              Number of patterns saved

Repeated for NOP:

len             description
---             -----------
 2              Number of events stored in this pattern
 4              Length of pattern starting with next byte
 1              Break location of pattern

What remains is an event for each thing that is to happen on any channel. This
eliminates the need for saving blank data like most tracker formats (such
as MOD). And while crunched formats like 669 work a lot towards saving space,
this format is still superior (most 669's are shrunk considerably based on
F2R file stats).

len             description
---             -----------
 1              Event Type. Each bit denotes a bit of information included:

      bit
      ---
       0        New note pitch
       1        New instrument value
       2        Starting of a new note is required
       3        New volume
       4        Effect 0 is specified - Note you can put up to 4 effects at
       5        Effect 1 is specified   once on one note if your tracker
       6        Effect 2 is specified   will do it. Each bit specifies
       7        Effect 3 is specified   an effect that is on this event.

 1              Channel

Each of the following is included only if the appropriate bit is set:

 1              ET0-(Octave*12)+Note
 1              ET1-Sample number
 1              ET3-Volume (0-FF)
 2              ET4-Effect #+effect data
 2              ET5-Effect #+effect data
 2              ET6-Effect #+effect data
 2              ET7-Effect #+effect data

Rest is always here:

 1              EventTick - number of ticks to wait before processing next
                event.

The above structure repeats for NumEvents (in pattern header) and the entire
pattern structure continues until all patterns are saved.

Effects are standard Farandole Composer effects. Note that effects up 0-FF
are supported, but FAR is only going to support 0-Z.


STXT
----

Songtext in ASCII format. This means each line is ended with a <CR> (no LF).
File is ended with an EOF (26).


SANS
----

Same as above, except that ANSI codes are permitted. Actually the actual ANSI
codes are not stored, but binary versions of them:

0-black
1-blue
2-green
3-cyan
4-red
5-magenta
6-brown
7-gray
8-15 - Same as 0-7 except high intensity

16-31 - Same as 0-15 except background colors

The palette used for ANSI scrolltext mode is the same palette used in
standard VGA text mode. This is so you can import regular TheDraw ANSI files
into FAR.


APIC
----

A picture of the author can be included here. It will be in DIF-RLE compressed
format which i use in demos, etc. Here's a rundown on that format:

word X size
word Y size
768 bytes palette
Compressed data. Decompression as follows:

Read byte. If byte is not equal to 255, then store byte in output. If it is
255, read next byte. If the next byte is a 255, then store a 255 in output.
If it's NOT 255, then use that number as a repeat count for the last valid
input byte. (I'll include code when it's useful.. you'll see :).

