home *** CD-ROM | disk | FTP | other *** search
/ Shareware Supreme Volume 6 #1 / swsii.zip / swsii / 361 / ADLBTEC1.ZIP / ADLIBMSC.ARC / BKFORMAT.TXT < prev    next >
Encoding:
Text File  |  1989-05-10  |  5.9 KB  |  152 lines
  1. Ad Lib, January 1989
  2. --------------------
  3.  
  4. The .INS instrument files have been grouped together to create a .BNK (bank)
  5. file.  The purpose of this is to save space.  DOS will allocate 1K of space
  6. for a file regardless of how small the file actually is.  So the bank file
  7. saves a significant amount of space.
  8.  
  9. We are currently modifying our software to use the .BNK file instead of
  10. .INS files.  The new software versions will all be numbered 1.5 and will
  11. not support the old .INS files.  However, a utility will be provided to
  12. convert between the two formats.  The default name for the bank file is
  13. STANDARD.BNK although any name may be used as long as the file extension
  14. is .BNK.
  15.  
  16. The .BNK file a basically a collection of the old .INS file structures (as
  17. shown in Appendix C of the Programmer's Manual) with the waveform added to
  18. the end.
  19.  
  20.  
  21. Structure of .BNK files
  22. -----------------------
  23.  
  24. FIELD#  SIZE-bytes  TYPE        DESCRIPTION
  25.  
  26.                                 HEADER
  27. 1       1           char        file version, major
  28. 2       1           char        file version, minor
  29. 3       6           char        signature: "ADLIB-"
  30. 4       2           unsigned    number of list entries used
  31. 5       2           unsigned    total number of list entries in file
  32. 6       4           long        absolute offset in file of start of name list
  33. 7       4           long        absolute offset in file of start of data
  34. 8       8           char        filler (set to zero)
  35.  
  36.                                 INSTRUMENT NAME SECTION RECORD
  37. 1       2           unsigned    index into data section
  38. 2       1           char        flag: 0 if this record is not used, else 1
  39. 3       9           char        instrument name (max 8 char + NULL)
  40.  
  41.                                 DATA SECTION RECORD
  42. 1       1           char        mode (0=melodic, 1=percussive)
  43. 2       1           char        voice number (if percussive mode)
  44. 3       13          char        modulator (operator 0) parameters
  45. 4       13          char        carrier (operator 1) parameters
  46. 5       1           char        wave form for modulator
  47. 6       1           char        wave form for carrier
  48.  
  49.  
  50. There is one header at the very beginning of the file.  Field #6 in the
  51. header is the absolute offset of the start of the instrument name section.
  52.  
  53. The instrument name section contains a list of records which contain the
  54. instrument name, a flag and a pointer to the data section.  Header field #5
  55. gives the total number of records in this list, although not all of these
  56. records may be in use.  Header field #4 gives the number of name records which
  57. are actually being used.  The records in use will be placed at the beginning
  58. of the section and will be arranged alphabetically by instrument name.
  59.  
  60. The data section contains the records of instrument parameters.  One of these
  61. records is equivalent to the .INS file structure, except that the 2-byte
  62. fields are now 1-byte long.  Two more bytes have been added for the wave
  63. form type for each operator.
  64.  
  65. So, to read an instrument from the new bank file:
  66. 1. Read the header.
  67. 2. Use header field #6 to do a seek to the start of the instrument name
  68.    section.
  69. 3. Search the name section for the desired name.  (The search is delimited
  70.    by header field #4.)
  71. 4. When found, get its index into the data section (name field #1).
  72. 5. Calculate the address where the data for this instument will be found:
  73.       header_field_#7 + (index * sizeof_data_record)
  74. 6. Do a seek to the calculated address and read the data.
  75.  
  76.  
  77. Notes
  78. -----
  79.  
  80. The instrument names are alphabetically arranged so that you are not limited
  81. to using a linear search method.  A binary search would be appropriate.
  82.  
  83. If you are going to be creating or deleting an instrument, you must preserve
  84. the alphabetical order of instrument names.  However, the data section is
  85. not neccesarily ordered.  When adding data, you can find the data record
  86. to use from the index pointer from the first unused instrument name
  87. record.
  88.  
  89. The unused instrument name records are not empty: the pointers into the data
  90. section are valid and are used when adding instruments.  When expanding the
  91. instrument name section, field #1 must be initialized to a valid value.
  92. (In this case, the data section must be shifted down and header field #7
  93. must be adjusted accordingly.)  The purpose of having empty name records is
  94. to avoid having to rewrite the entire file every time an instrument is added.
  95.  
  96.  
  97. C Structures
  98. ------------
  99. The following are C structures which correspond to the information
  100. given above.
  101.  
  102.  
  103. /* Instrument bank file header */
  104. typedef struct {
  105.    char      majorVersion;
  106.    char      minorVersion;
  107.    char      sig [6];            /* signature: "ADLIB-" */
  108.    unsigned  nrDefined;          /* number of list entries used */
  109.    unsigned  nrEntry;            /* number of total entries in list */
  110.    long      offsetIndex;        /* offset in file of start of name list */
  111.    long      offsetTimbre;       /* offset in file of start of data */
  112.    char      filler [8];         /* must be zero */
  113. } BankHeader;
  114.  
  115.  
  116. /* Name of instrument with a pointer to its position in the file */
  117. typedef struct {
  118.    unsigned nrReference;       /* index into data section */
  119.    char  usedFlag;             /* 0 if this entry is not used */
  120.    char  TimbreName [9];       /* max 8 char's + NULL */
  121. } BankEntry;
  122.  
  123.  
  124. /* Operator structure */
  125. typedef struct {
  126.    char  ksl;
  127.    char  freqMult;
  128.    char  feedBack;              /* used by operator 0 only */
  129.    char  attack;
  130.    char  sustLevel;
  131.    char  sustain;
  132.    char  decay;
  133.    char  release;
  134.    char  output;
  135.    char  am;
  136.    char  vib;
  137.    char  ksr;
  138.    char  fm;                    /* used by operator 0 only */
  139. } Operator;
  140.  
  141.  
  142. typedef struct {
  143.     char      mode;
  144.     char      percVoice;
  145.     Operator  op0;
  146.     Operator  op1;
  147.     char      wave0;            /* wave form for operator 0 */
  148.     char      wave1;            /* wave form for operator 1 */
  149. } PackedTimbre;
  150.  
  151.  
  152.