git.cworth.org Git - scherzo/blob - score.h

   1 /* scherzo - Music notation training
   2  *
   3  *      score - Utilities for drawing (simple) musical scores
   4  *
   5  * Copyright © 2010 Carl Worth
   6  *
   7  * This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation, either version 3 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program.  If not, see http://www.gnu.org/licenses/ .
  19  */
  20
  21 #ifndef SCORE_H
  22 #define SCORE_H
  23
  24 #include <talloc.h>
  25 #include <cairo.h>
  26
  27 #include "pitch.h"
  28
  29 typedef enum score_duration
  30 {
  31     SCORE_DURATION_WHOLE = 1,
  32     SCORE_DURATION_1 = 1,
  33     SCORE_DURATION_HALF = 2,
  34     SCORE_DURATION_2 = 2,
  35     SCORE_DURATION_QUARTER = 4,
  36     SCORE_DURATION_4 = 4,
  37     SCORE_DURATION_EIGHTH = 8,
  38     SCORE_DURATION_8 = 8,
  39     SCORE_DURATION_SIXTEENTH = 16,
  40     SCORE_DURATION_16 = 16,
  41     SCORE_DURATION_THIRTYSECOND = 32,
  42     SCORE_DURATION_32 = 32,
  43     SCORE_DURATION_SIXTYFOURTH = 64,
  44     SCORE_DURATION_64 = 64,
  45     SCORE_DURATION_ONEHUNDREDTWENTYEIGHTH = 128,
  46     SCORE_DURATION_128 = 128
  47 } score_duration_t;
  48
  49 #define SCORE_BUILD_NOTE(pitch, octave, duration) SCORE_PITCH_##pitch, (octave), SCORE_DURATION_##duration
  50
  51 typedef struct score score_t;
  52 typedef struct score_staff score_staff_t;
  53
  54 typedef struct score_note
  55 {
  56     score_staff_t *staff;
  57     pitch_t pitch;
  58     score_duration_t duration;
  59
  60     struct {
  61         double r;
  62         double g;
  63         double b;
  64     } color;
  65 } score_note_t;
  66
  67 typedef struct score_chord
  68 {
  69     score_staff_t *staff;
  70
  71     char *name;
  72     double width;
  73 } score_chord_t;
  74
  75 typedef enum score_clef
  76 {
  77     SCORE_CLEF_G,
  78     SCORE_CLEF_TREBLE = SCORE_CLEF_G,
  79     SCORE_CLEF_F,
  80     SCORE_CLEF_BASS = SCORE_CLEF_F
  81 } score_clef_t;
  82
  83 /* Allocate a new, empty score object, (with optional ctx as talloc
  84  * owner). If ctx is NULL, the caller should call talloc_free on the
  85  * score_t* when done with it. Otherwise, the object will be freed
  86  * when ctx is freed. */
  87 score_t *
  88 score_create (void *ctx);
  89
  90 /* Set an (approximate) staff height. The actual staff height may
  91  * differ due to rounding to achieve evenly spaced, sharply rendered
  92  * lines. the actual staff height is returned. */
  93 int
  94 score_set_staff_height (score_t *score, int height);
  95
  96 /* Set the total width available for drawing the score. */
  97 void
  98 score_set_width (score_t *score, int width);
  99
 100 /* Add a brace to the score, connecting the given number of staves.
 101  *
 102  * The staves to be connected are those that will next be added to the
 103  * score. */
 104 void
 105 score_add_brace (score_t *score, int staves);
 106
 107 /* Add a new staff to the score */
 108 score_staff_t *
 109 score_add_staff (score_t *score, score_clef_t clef);
 110
 111 /* Add a note to a staff of the given pitch and duration.
 112  *
 113  * Duration values can be symbolic (SCORE_DURATION_WHOLE, _QUARTER,
 114  * _EIGHTH, etc.) or numerical as simply the denominator (WHOLE=1,
 115  * QUARTER=4, EIGHTH=8, etc.)
 116  */
 117 void
 118 score_staff_add_note (score_staff_t *staff,
 119                       pitch_t pitch,
 120                       score_duration_t duration);
 121
 122 /* Add a note to the score, (automatically selecting the nearest
 123  * staff) */
 124 void
 125 score_add_note (score_t *score, pitch_t pitch, score_duration_t duration);
 126
 127 /* Add a chord symbol of 'name' to a staff.
 128  *
 129  * For now, the chord symbols are free-form names.
 130  *
 131  * The chord name must be a talloc'ed string, which the returned
 132  * score_chord_t will talloc_steal.
 133  */
 134 score_chord_t *
 135 score_add_chord (score_staff_t *staff,
 136                  const char * name);
 137
 138 /* Remove the given chord from its staff. */
 139 void
 140 score_remove_chord (score_chord_t *chord);
 141
 142 /* Remove the given note from its staff. */
 143 void
 144 score_remove_note (score_note_t *note);
 145
 146 /* Remove all notes from the given staff. */
 147 void
 148 score_staff_remove_notes (score_staff_t *staff);
 149
 150 /* Remove all notes from the score. */
 151 void
 152 score_remove_notes (score_t *score);
 153
 154 void
 155 score_set_note_color_rgb (score_note_t *note,
 156                           double r,
 157                           double g,
 158                           double b);
 159
 160 /* Return the first note on the given staff with the given pitch,
 161  * octave, and durations. Returns NULL if no match is found. */
 162 score_note_t *
 163 score_staff_find_note (score_staff_t *staff,
 164                        pitch_t pitch,
 165                        score_duration_t duration);
 166
 167 /* Draw the given score_t onto the given cairo_t.
 168  *
 169  * The caller can call cairo_translate before calling score_draw to
 170  * position the result as desired, (and can call cairo_clip to clip it
 171  * if desired). */
 172 void
 173 score_draw (score_t *score, cairo_t *cr);
 174
 175 #endif