./../../src/change-map.lsp

## change-map/cm-get-data [ Methods ]

[ Top ] [ change-map ] [ Methods ]

DESCRIPTION

     Return the data for a specified section and player of a given change-map
     object.

     NB: The <section> argument may require the ID of the player as well if
         used, for example, with the instrument-change-map subclass of this
         class .

ARGUMENTS

     - A change-map object.
     - A simple key reference into the given change-map object or a list of
       references. NB: This reference may require a player ID if, for example,
       used with an instrument-change-map subclass of this class.

OPTIONAL ARGUMENTS

     - The ID of the sequence from which to return the change-map data.
     - An integer that is the bar number for which to return the change-map
       data.

RETURN VALUE

     The change-map data stored at the specified location within the given
     change-map.

EXAMPLE

    ;;; An example using the instrument-change-map subclass of change-map

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((sax ((alto-sax tenor-sax) :midi-channel 1))))
            :instrument-change-map '((1 ((sax ((1 alto-sax) (3 tenor-sax)))))
                                     (2 ((sax ((2 alto-sax) (5 tenor-sax)))))
                                     (3 ((sax ((3 alto-sax) (4 tenor-sax))))))
            :set-palette '((1 ((c2 d2 g2 a2 e3 fs3 b3 cs4 fs4 gs4 ds5 f5 bf5))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (1 1 1 1 1))
                       (3 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((sax (1 1 1 1 1))))
                            (2 ((sax (1 1 1 1 1))))
                            (3 ((sax (1 1 1 1 1))))))))
      (cm-get-data (instrument-change-map mini) '(2 sax) 4))

    => ALTO-SAX

SYNOPSIS

    (defmethod cm-get-data ((cm change-map) section
                            &optional (sequence 1) (bar 1))

## change-map/find-nearest [ Methods ]

[ Top ] [ change-map ] [ Methods ]

DESCRIPTION

     Return the nearest change-data object to the specified section within the
     given change-map. NB: The section may require a player ID if used, for
     example, with an instrument-change-map subclass of change-map.

ARGUMENTS

     - A section indication, either as a single reference ID or a list of
       reference IDs into the given change-map.
     - A change-map object.

RETURN VALUE

     Returns a change-data object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((sax ((alto-sax tenor-sax) :midi-channel 1))))
            :instrument-change-map '((1 ((sax ((1 alto-sax) (3 tenor-sax)))))
                                     (2 ((sax ((2 alto-sax) (5 tenor-sax)))))
                                     (3 ((sax ((3 alto-sax) (4 tenor-sax))))))
            :set-palette '((1 ((c2 d2 g2 a2 e3 fs3 b3 cs4 fs4 gs4 ds5 f5 bf5))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (1 1 1 1 1))
                       (3 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((sax (1 1 1 1 1))))
                            (2 ((sax (1 1 1 1 1))))
                            (3 ((sax (1 1 1 1 1))))))))
      (find-nearest '(4 sax) (instrument-change-map mini)))

    =>
    CHANGE-DATA:
                previous-data: TENOR-SAX,
                last-data: TENOR-SAX
    SCLIST: sclist-length: 2, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: (2 SAX), this: (3 SAX), next: NIL
    NAMED-OBJECT: id: SAX, tag: NIL,
    data: ((3 1 ALTO-SAX) (4 1 TENOR-SAX))

SYNOPSIS

    (defmethod find-nearest (section (cm change-map))

## sc-map/change-map [ Classes ]

[ Top ] [ sc-map ] [ Classes ]

NAME

     change-map

     File:             change-map.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist ->
                       circular-sclist -> assoc-list -> recursive-assoc-list ->
                       sc-map -> change-map

     Version:          1.0.1

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the change-map class where, unlike
                       normal sc-maps (data is given for each sequence) gives
                       data sporadically when the parameter changes, for
                       instance tempo.

                       It is assumed that maps will be typed in the order in
                       which sections occur so that previous-data slots can be
                       kept up-to-date; also, unless all data will be given,
                       that the sections (but not instrument ids) will be in
                       integer sequential order so that nearest sections can be
                       returned when given a non-existent section reference.

                       For example, the following change-map indicates tempo
                       (though tempo-maps have their own class now).
                       It has sections within sections so that the tempo for
                       section '(1 2 3) can be defined, that is, section 1 has
                       subsections 1, 2, and 3 and subsection 2 has further
                       subsections 1, 2, and 3.  This can be nested to any
                       depth.  The tempo information itself is given in sublists
                       where (3 27) means that in the third sequence of the
                       section, the tempo is 27.  (3 2 27) means the 2nd bar of
                       the third sequence has tempo 27: when only two numbers
                       are in the list, bar 1 is assumed.  The trick is, that
                       this tempo then remains, as would be expected, until the
                       next tempo change is indicated, which means that
                       requesting the tempo of section (2 2 3) with any sequence
                       and bar in the map below would return 25, because that is
                       the last tempo given in section 1 and no tempo is defined
                       for section 2.

                       (setf x
                         (make-change-map
                          'test nil
                          '((0 ((3 27) (9 3 45)))
                            (1
                             ((1 ((1 21) (5 28) (8 35) (3 2 40) (3 1 54)))
                              (2
                               ((1 ((1 23) (6 28) (18 35)))
                                (2 ((2 2 24) (7 28) (18 22)))
                                (3 ((3 34) (7 28) (18 42)))))
                              (3 ((1 22) (5 34) (10 5 25)))))
                            (4
                             ((1 ((1 21) (5 28) (8 36) (3 2 40) (3 1 55)))
                              (2 ((1 22) (5 34) (10 5 103)))))
                            (5 ((2 28) (6 3 45)))
                            (10
                             ((1 ((1 21) (5 28) (8 37) (3 2 40) (3 1 56)))
                              (2 ((1 22) (5 34) (10 5 27))))))))

                       You have to be careful with change-maps however as the
                       nesting is flexible and therefore ambiguous.  For
                       instance, in the following the bcl, tape1 etc. ids are
                       not subsections of section 1, rather these are the hint
                       pitches assigned to the instruments in section 1 (which
                       has no subsections).  This is where the last-ref-required
                       class slot comes in:  If this slot is t (this is the
                       second argument to make-change-map) then the last
                       reference in a call to cm-get-data is always respected,
                       i.e. not the last data given will be returned when the
                       section doesn't exist, rather the last data for this
                       reference.  E.g. In the following map, if
                       last-ref-required  were nil, then the call to
                       (cm-get-data x '(2 tape2) 1) would fail (because we can't
                       find nearest data when references aren't numbers), but
                       because it's t, we get the last data given for tape2 and
                       return cs5.

                       (setf x
                         (make-change-map
                             'hint-pitches t
                             '((1 ((bcl ((1 a4) (2 b4) (3 c5) (4 d6)))
                                   (tape1 ((1 a3) (2 ds2) (3 e4)))
                                   (tape2 ((1 a3) (2 ds2) (3 cs5)))
                                   (tape3 ((1 a3) (2 ds2) (3 eqf4)))))
                               (2 ((bcl ((1 a4) (2 b4) (3 c5) (4 d6)))
                                   (tape1 ((1 a3) (2 ds2) (5 fs4)))))
                               (3 ((bcl ((1 a4) (2 b4) (3 c5) (4 d6)))
                                   (tape1 ((1 a3) (2 ds2) (5 f4))))))))

     Author:           Michael Edwards: m@michael-edwards.org

     Creation date:    2nd April 2001

     $$ Last modified: 21:14:11 Thu Dec  8 2011 ICT

     SVN ID: $Id: change-map.lsp 3360 2012-12-16 03:37:53Z medward2 $