1 /* scherzo - Music notation training
3 * score - Utilities for drawing (simple) musical scores
5 * Copyright © 2010 Carl Worth
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.
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.
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/ .
29 typedef enum score_duration
31 SCORE_DURATION_WHOLE = 1,
33 SCORE_DURATION_HALF = 2,
35 SCORE_DURATION_QUARTER = 4,
37 SCORE_DURATION_EIGHTH = 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
49 #define SCORE_BUILD_NOTE(pitch, octave, duration) SCORE_PITCH_##pitch, (octave), SCORE_DURATION_##duration
51 typedef struct score score_t;
52 typedef struct score_staff score_staff_t;
54 typedef struct score_note
58 score_duration_t duration;
67 typedef struct score_chord
75 typedef enum score_clef
78 SCORE_CLEF_TREBLE = SCORE_CLEF_G,
80 SCORE_CLEF_BASS = SCORE_CLEF_F
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. */
88 score_create (void *ctx);
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. */
94 score_set_staff_height (score_t *score, int height);
96 /* Set the total width available for drawing the score. */
98 score_set_width (score_t *score, int width);
100 /* Add a brace to the score, connecting the given number of staves.
102 * The staves to be connected are those that will next be added to the
105 score_add_brace (score_t *score, int staves);
107 /* Add a new staff to the score */
109 score_add_staff (score_t *score, score_clef_t clef);
111 /* Add a note to a staff of the given pitch and duration.
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.)
118 score_staff_add_note (score_staff_t *staff,
120 score_duration_t duration);
122 /* Add a note to the score, (automatically selecting the nearest
125 score_add_note (score_t *score, pitch_t pitch, score_duration_t duration);
127 /* Add a chord symbol of 'name' to a staff.
129 * For now, the chord symbols are free-form names.
131 * The chord name must be a talloc'ed string, which the returned
132 * score_chord_t will talloc_steal.
135 score_add_chord (score_staff_t *staff,
138 /* Remove the given chord from its staff. */
140 score_remove_chord (score_chord_t *chord);
142 /* Remove the given note from its staff. */
144 score_remove_note (score_note_t *note);
146 /* Remove all notes from the given staff. */
148 score_staff_remove_notes (score_staff_t *staff);
150 /* Remove all notes from the score. */
152 score_remove_notes (score_t *score);
155 score_set_note_color_rgb (score_note_t *note,
160 /* Return the first note on the given staff with the given pitch,
161 * octave, and durations. Returns NULL if no match is found. */
163 score_staff_find_note (score_staff_t *staff,
165 score_duration_t duration);
167 /* Draw the given score_t onto the given cairo_t.
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
173 score_draw (score_t *score, cairo_t *cr);