seq.h

   1 typedef struct track track;
   2 typedef struct block block;
   3 typedef struct chunk chunk;
   4 typedef struct event event;
   5 typedef struct chunk_list chunk_list;
   6
   7
   8
   9 struct track {
  10         int port; /* read / write */
  11         int chan; /* read / write */
  12         block* blocks;
  13         block* block_ptr;
  14         struct track* next;
  15 };
  16
  17 struct block {
  18         unsigned tick; /* read */
  19         int length; /* read */
  20         chunk* chunk_ptr; /* read */
  21         chunk_list* chunks;
  22         event* event_ptr;
  23         struct block* next;
  24 };
  25
  26 struct chunk {
  27         int r, g, b; /* read / write */
  28         int ref_c;
  29         event* events;
  30 };
  31
  32 struct chunk_list {
  33         chunk* ptr;
  34         struct chunk_list* next;
  35 };
  36
  37 struct event {
  38         unsigned tick; /* read */
  39         int type; /* read */
  40         int u, v; /* read */
  41         struct event* next;
  42 };
  43
  44
  45 /* play / stop */
  46 void seq_play(int on_off);
  47 unsigned seq_poll(void);
  48 void seq_seek(unsigned tick);
  49 void seq_reset(void);
  50 void seq_record(int on_off);
  51 void seq_set_record_track(int n);/* FIXME */
  52 void seq_loop(int on_off);
  53 void seq_loop_limits(unsigned tick1, unsigned tick2);
  54 void seq_time_config(unsigned sr, unsigned tpb, unsigned bpm);
  55 void seq_all_notes_off(void);
  56
  57 /* */
  58 void seq_init(void* (*aloc)(size_t), void (*fr)(void*), int (*oom)(void));
  59 void seq_uninit(void);
  60 int seq_undo(void);
  61 int seq_redo(void);
  62 void seq_commit(void);
  63 void seq_clear_all(void);
  64 void seq_instant(track* tr, int type, int u, int v);
  65 chunk* seq_mk_chunk(void);
  66
  67 void seq_dump(void);
  68
  69
  70 /* these operations can be undone */
  71 void seq_add_track(void);
  72 void seq_delete_track(track* tr);
  73 void seq_insert_block(track* tr, unsigned tick, chunk* ck);
  74 void seq_copy_block(block* bl, track* tr, unsigned tick);
  75 void seq_resize_block(block* bl, unsigned length);
  76 void seq_delete_block(block* bl);
  77 void seq_push_chunk(block* bl, chunk* ck);
  78 void seq_rrotate_chunk(block* bl);
  79 void seq_lrotate_chunk(block* bl);
  80 void seq_insert_event(chunk* ck, unsigned tick, int type, int u, int v);
  81 void seq_delete_event(chunk* ck, event* ev);
  82 void seq_accept_recording(void);
  83
  84 /* sequencer state reading */
  85 int seq_layer_number(block* bl);
  86 void seq_walk_tracks(void);
  87 track* seq_next_track(void);
  88 void seq_walk_blocks(track* tr);
  89 block* seq_next_block(void);
  90 void seq_walk_events(chunk* ck);
  91 event* seq_next_event(void);
  92
  93 /* audio thread operations */
  94 int seq_advance(unsigned samples, unsigned* used,
  95         int* port, int* type, int* chan, int* u, int* v);
  96 void seq_record_event(int type, int chan, int u, int v);
  97
  98 /*
  99 sequencer operation
 100
 101 the sequencer is an abstract machine with the following
 102 stateful components.
 103
 104 the sequence itself is a set of tracks, which hold a scheduled
 105 set of blocks, which hold an order set of event chunks (layers),
 106 each of which holds a scheduled set of midi events. there are
 107 several raw commands to manipulate the sequence by creating, deleting,
 108 moving, and inserting the above elements. chunks may be shared among
 109 many blocks, changes in one block may affect others (because they
 110 point to the same chunk).
 111
 112 the undo history remembers one branch of manipulation commands and
 113 can be used to reverse edits back to the beginning of time. there is
 114 an operation to commit changes so that undo can skip back several
 115 edits at a time. this allows support for implementing more complex
 116 edit operations. the undo history is partially erased every time
 117 you commit.
 118
 119 the play head is a single number that tells the sequencer where it
 120 is in time. there are operations to set the play position. the
 121 play head is naturally advanced using the advance operation, which
 122 also returns the next event to play. when the record operation is
 123 used, an event will be written to the sequence at the current
 124 play head position. when the sequencer is set to play, advance will
 125 actually move the play head and emit events. otherwise advance will
 126 not move the play head and emit no events except those in the instant
 127 queue. see below.
 128
 129 the sequencer has three parameters which are used to control the
 130 real world speed of playback. sample_rate determines the conversion
 131 between samples (used by seq_advance) and real time. ticks_per_beat
 132 determines the conversion between beats (used in tempo) and abstract
 133 tick time units (used by the sequencer). beats_per_week (tempo) determines
 134 the conversion between beats and real time. 1 week is (7*86400) seconds.
 135 the unit of time in almost all the sequencer operations is in ticks.
 136 altering the tempo, sample rate, or ticks per beat during playback may
 137 introduce a one time small time error.
 138
 139 an 'instant queue' contains events will must be scheduled immediately
 140 and will never occur again. there is an operation to enqueue events
 141 for immediate dispatch. as the output mechanism advances the sequencer
 142 play head (using seq_advance) the events in the instant queue will be
 143 dequeued.
 144
 145 an unit which tracks current note ons. when certain operations take
 146 place the sequencer will emit instant events to cancel these events.
 147 this unit is updated when the audio thread advances the play head.
 148
 149 there may be at most two agents which operate on the sequencer, known
 150 as the editor and the audio thread. the audio thread is limited to only
 151 two operations: seq_advance and seq_record_event. both of these operations
 152 have side effects on the sequencer state but are carefully designed to
 153 avoid race conditions and minimize audio thread latency.
 154
 155 */