Structure INSTR
Prev | Chapter 4. Objects | Next

## Structure INSTR

An `INSTR` structure contain instrument-specific data that's used to inform FOMUS on various aspects of notation. Instruments are specified in the `INSTR` slot of `PART` objects and can be easily modified. Users can also build their own "database" of instruments by creating a FOMUS initialization file (see Initialization File).

Constructor: `(MAKE-INSTR &key :SYM `sym` :CLEFS `clefs` :STAVES `staves` :MINP `minp` :MAXP `maxp` :SIMULTLIM `simultlim` :TPOSE `tpose` :CLEFLEGLS `cleflegls` :8UPLEGLS `8uplegls` :8DNLEGLS `8dnlegls` :PERCS `percs` :MIDIPRGCH-IM `midiprgch-im` :MIDIPRGCH-EX `midiprgch-ex`)`

Copy Function: `(COPY-INSTR `instr` &key :SYM `sym` :CLEFS `clefs` :STAVES `staves` :MINP `minp` :MAXP `maxp` :SIMULTLIM `simultlim` :TPOSE `tpose` :CLEFLEGLS `cleflegls` :8UPLEGLS `8uplegls` :8DNLEGLS `8dnlegls` :PERCS `percs` :MIDIPRGCH-IM `midiprgch-im` :MIDIPRGCH-EX `midiprgch-ex`)`

Predicate Function: `(INSTRP `obj`)`

Accessors:

`INSTR-SYM`

  This is a unique symbol identifying the instrument. It is used as a lookup value so that it may easily be specified in `PART` objects.

`INSTR-CLEFS`

  This is either a symbol or list of symbols, specifying valid clefs for the instrument in order of preference. The following clefs are supported: `:bass`, `:c-baritone`, `:f-baritone`, `:tenor`, `:alto`, `:mezzosoprano`, `:soprano`, `:treble` and `:percussion`. The user may also add an `-8UP` or `-8DN` suffix to the symbol to specify an octave transposition.

`INSTR-STAVES`

  This is an integer specifying the number of staves to use. The default is 1.

`INSTR-MINP`

  This is an integer specifying the lowest pitch in the instrument's range. It may also be set to `NIL`, in which case the lower range is considered to be unlimited. This is only useful if the `CHECK-RANGES` setting is set to `T`.

`INSTR-MAXP`

  This is an integer specifying the highest pitch in the instrument's range. It may also be set to `NIL`, in which case the upper range is considered to be unlimited. This is only useful if the `CHECK-RANGES` setting is set to `T`.

`INSTR-SIMULTLIM`

  This is an integer of `1` or greater specifying the maximum number of simultaneous pitches allowed in a single voice. It may also be set to `NIL`, indicating that there is no limit.

`INSTR-TPOSE`

  This is set to the value `NIL` or an integer indicating the number of semitones to transpose the instrument before notating it. This number only has an effect if the `TRANSPOSE` setting is set to `T`.

`INSTR-CLEFLEGLS`

  The value of this slot influences how FOMUS decides when to change clefs. A clef change isn't considered necessary until the number of ledger lines required exceeds a threshold value. Other factors determine if there is actually a clef change or not. If the value is an integer, it designates the threshold number of ledger lines in all cases. If it's a list, the first element of the list must be an integer specifying a default threshold. This is followed by one or more exceptions, each in the form of a list. This exception list contains a clef symbol (see the `CLEFS` slot above) followed by one of the two symbols `:UP` or `:DN` and ended by an integer specifying the number of ledger lines. An example illustrates this data structure.

  Example 4.10. INSTR-CLEFLEGLS Slot Setting

      '(2 (:bass :up 3) (:tenor :down 3))

`INSTR-8UPLEGLS`

  This value influences how FOMUS chooses where to place ottava brackets above the staff. An ottava bracket isn't considered necessary until the number of ledger lines required exceeds a threshold value. An integer in this slot indicates the threshold value, while a list of two elements specifies the threshold for the ottava bracket to begin and the threshold below which the number of ledger lines must drop for it to end.

`INSTR-8DNLEGLS`

  This is the same as `INSTR-8UPLEGLS` above, only for ottava brackets placed below the staff

`INSTR-PERCS`

  This is a list of symbols, `PERC` objects, numbers or lists indicating all of the percussion instruments that are to be notated together as a group. `PERC` objects provide necessary extra information for notating percussion. All of these value types function to lookup percussion instruments in the same way as the `PART-INSTR` slot of the `PART` class. Symbols are used as lookup values into a user-defined percussion instrument table (see the `PERCUSSION` setting) or FOMUS's own predefined table. Lists contain a symbol lookup value followed by keyword-argument pairs signifying values to replace in the predefined percussion table--it will usually be necessary to use a list instead of a symbol since the `NOTE` and `VOICE` slots are empty in FOMUS's table.

  Example 4.11. INSTR-PERCS Slot Setting

      (list '(:low-tom :note 0 :voice 1) '(:high-tom :note 4 :voice 1)
            (make-perc :anvil :note -3 :voice 2 :midinote-ex 79))

`MIDIPRGCH-IM`

  This is a number from `0` to `127` or a list of such numbers specifying which MIDI program change values can translate to this instrument. This is used when specifying an instrument as a program change number (see the `INSTR` slot in the `PART` class) or calling the `GET-MIDI-INSTR` function. When given a program change number, FOMUS finds the first instrument that matches in its list.

`MIDIPRGCH-EX`

  This is usually a number from `0` to `127` specifying which program change value is to be used when exporting MIDI data. It can also be set to a list, the first element of which is the number mentioned above followed by keyword/value pairs indicating alternate program change values for different playing modes. (For example, the list `'(40 :pizz 45)` is a valid value for a violin instrument.) The keywords currently allowed are `:PIZZ`, `:STOPPED`, `:OPEN` and `:HARMONIC`. (More will be added in future releases.)

Prev | Up | Next
Class MARK | Home | Structure PERC