sscore_playdata.h
IntroductionThe C interface to play information in SeeScoreLib The barindex parameter is zero-based. ie 0 is the first bar in the score. All times are in milliseconds C Pseudoclasses
Groupssscore_playdataGroup members:
sscore_pd_barnotes_iteratorGroup members:
sscore_pd_bar_iteratorall functions must be called on a single thread Group members:
Functions
sscore_pd_actualbeatsforbarget the effective time signature information for a bar EXPORT enum sscore_error sscore_pd_actualbeatsforbar( const sscore *sc, int barindex, sscore_timesig *timesig); ParametersReturn Valueany error DiscussionThis should return the same value as sscore_timesigforbar for a full bar, less for a partial bar sscore_pd_bartypeforbarget information about a partial bar with fewer beats than the time signature (anacrusis or double-barline bar) EXPORT enum sscore_bartype_e sscore_pd_bartypeforbar( const sscore *sc, int barindex); ParametersReturn Valuetype of partial bar Discussionit is important to know if a partial bar contains the first beat or the last beat sscore_pd_beginan iterator to the start bar of the piece (viz STL container) EXPORT sscore_pd_bar_iterator sscore_pd_begin( sscore_playdata *pd); ParametersReturn Valuean iterator to the start bar of the piece Discussionincrement the iterator to move to the next bar in play order allowing for repeats sscore_pd_bi_bardurationthe duration of the current bar in ms EXPORT int sscore_pd_bi_barduration( sscore_pd_bar_iterator *bi); ParametersReturn Valueduration of bar in ms sscore_pd_bi_barindexget the index of the current bar EXPORT int sscore_pd_bi_barindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe index of the bar which the iterator refers to (0 during count-in and first bar) sscore_pd_bi_beginan iterator to notes in the current and next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_begin( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe start barnotes iterator pointing to the first played note in the bar. Discussionincrement the returned iterator (sscore_pd_bni_inc) to move to the next note in time order in the given part 'dereference' the iterator (sscore_pd_bni_getnote) to get the note information NB The iterator never returns the right hand note of a tie, as that only modifies the duration of the first tied note sscore_pd_bi_changebarmove the bar iterator to the given bar index EXPORT bool sscore_pd_bi_changebar( sscore_pd_bar_iterator *bi, int barindex); ParametersReturn Valuetrue if successful sscore_pd_bi_countinis this iterator in the count-in before the first bar? EXPORT bool sscore_pd_bi_countin( const sscore_pd_bar_iterator *bi); ParametersReturn Valuetrue during count-in before first bar sscore_pd_bi_decmove the bar iterator to the previous bar accounting for repeats. Unchanged if at beginning EXPORT void sscore_pd_bi_dec( sscore_pd_bar_iterator *bi); Parameterssscore_pd_bi_endnextan iterator 1 past the last note in next bar so begin->endnext includes all notes in 2 bars so that the bar transition is covered EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_endnext( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe past-end barnotes iterator Discussioncompare a barnotes iterator with this to detect the end of sequence sscore_pd_bi_endthisan iterator 1 past the last note in the bar/part EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_endthis( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe past-end barnotes iterator Discussioncompare a barnotes iterator with this to detect the end of sequence for the bar sscore_pd_bi_equalcompare 2 iterators EXPORT bool sscore_pd_bi_equal( const sscore_pd_bar_iterator *bi1, const sscore_pd_bar_iterator *bi2); ParametersReturn Valuetrue if iterators are equal (point to the same bar, same repeat) sscore_pd_bi_getnotesampleinfoget information about notes required for preloading note samples ahead of time EXPORT enum sscore_error sscore_pd_bi_getnotesampleinfo( const sscore_pd_bar_iterator *bi, int numbars, const sscore_pd_partset *partset, sscore_pd_notesamples *rval); Parameters
Return Valueany error sscore_pd_bi_incmove the bar iterator to the next bar accounting for repeats. Unchanged if at end EXPORT void sscore_pd_bi_inc( sscore_pd_bar_iterator *bi); Parameterssscore_pd_bi_lesscompare 2 iterators EXPORT bool sscore_pd_bi_less( const sscore_pd_bar_iterator *bi1, const sscore_pd_bar_iterator *bi2); ParametersReturn Valuetrue if bi1 is at an earlier bar than bi2 sscore_pd_bi_metronome_beginan iterator to pseudo metronome notes in the current and next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_begin( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator Discussionthe metronome is modelled as a series of notes, 1 per beat in each bar. The correct bar sequence time signature changes are followed sscore_pd_bi_metronome_endnextan iterator 1 past the last note in the metronome sequence for this bar and the next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_endnext( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator sscore_pd_bi_metronome_endthisan iterator 1 past the last note in the metronome sequence for the bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_endthis( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator sscore_pd_bi_nextbarindexindex of next bar EXPORT int sscore_pd_bi_nextbarindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valueindex of the next bar after inc if canadvance, else sscore_pd_kAfterEndBarIndex sscore_pd_bi_seqindexplay index of bar in nondecreasing sequence EXPORT int sscore_pd_bi_seqindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valuesequential play index of the bar accounting for any repeats sscore_pd_bni_decdecrement the barnotes iterator so sscore_pd_bni_getnote returns the previous note EXPORT void sscore_pd_bni_dec( sscore_pd_barnotes_iterator *bni); Parameterssscore_pd_bni_equalcompare 2 iterators EXPORT bool sscore_pd_bni_equal( const sscore_pd_barnotes_iterator *bni1, const sscore_pd_barnotes_iterator *bni2); ParametersReturn Valuetrue if iterators are equal sscore_pd_bni_getnoteget the note information at the current iterator position EXPORT sscore_pd_note sscore_pd_bni_getnote( const sscore_pd_barnotes_iterator *bni); ParametersReturn Valueplay information about a note sscore_pd_bni_incincrement the barnotes iterator so sscore_pd_bni_getnote returns the next note EXPORT void sscore_pd_bni_inc( sscore_pd_barnotes_iterator *bni); ParametersDiscussionnotes are returned in non-decreasing start time order sscore_pd_bni_lesscompare 2 iterators EXPORT bool sscore_pd_bni_less( const sscore_pd_barnotes_iterator *bni1, const sscore_pd_barnotes_iterator *bni2); ParametersReturn Valuetrue if bni1 is earlier in the score than bni2 (assuming same playdata and part) sscore_pd_converttempotobpmconvert a tempo with a given beat type to the given time sig beat type EXPORT int sscore_pd_converttempotobpm( const sscore_pd_tempo *tempo, const sscore_timesig *timesig); ParametersReturn Valuebeats per minute Discussionthis is useful for converting sound tempo values, which are always crotchet relative (beat = 4) to the current time signature sscore_pd_disposeplaydatadispose the playdata EXPORT void sscore_pd_disposeplaydata( sscore_playdata *pd); ParametersDiscussiondispose the memory allocated for this by sscore_pd_newplaydata sscore_pd_endan iterator to 1 past the end bar of the piece EXPORT sscore_pd_bar_iterator sscore_pd_end( sscore_playdata *pd); ParametersReturn Valuean iterator to 1 past the end bar of the piece Discussionif the iterator is equal to this then the play is finished sscore_pd_firstbaranacrusisdetect partial first bar (anacrusis) EXPORT bool sscore_pd_firstbaranacrusis( const sscore_playdata *pd); ParametersReturn Valuetrue if 1st bar starts after first beat sscore_pd_getbarbeatsget the beats and divisions in a bar and the duration EXPORT enum sscore_error sscore_pd_getbarbeats( const sscore *sc, int barindex, int bpm, enum sscore_bartype_e bartype, sscore_pd_barbeats *barbeats); Parameters
Return Valueany error sscore_pd_getusertempoget user tempo struct EXPORT sscore_pd_usertempo sscore_pd_getusertempo( const sscore_playdata *pd); ParametersReturn Valuethe user tempo sscore_pd_hasdefinedtempois tempo defined in the score? EXPORT bool sscore_pd_hasdefinedtempo( const sscore *sc); ParametersReturn Valuetrue if the score defines tempo (metronome or sound tempo element). DiscussionIf this returns true then sscore_pd_usertempo.get_user_tempo_scaling will be called, else sscore_pd_usertempo.get_user_bpm will be used sscore_pd_maxdynamicmaximum value of any sound dynamic value in all bars EXPORT float sscore_pd_maxdynamic( const sscore_playdata *pd); ParametersReturn Valuemax sound dynamic value in score or 0 if none defined sscore_pd_metronomeforbarget any metronome defined in or before a bar EXPORT enum sscore_error sscore_pd_metronomeforbar( const sscore *sc, int barindex, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no metronome value defined sscore_pd_newplaydatacreate playdata which provides iterators for bar and note access EXPORT sscore_playdata *sscore_pd_newplaydata( const sscore *sc, const sscore_pd_usertempo *usertempo, int countinbars, const sscore_libkeytype *key); Parameters
Return Valuepointer to new playdata sscore_pd_numpartsEXPORT int sscore_pd_numparts( const sscore_playdata *pd); Return Valuenumber of parts in score sscore_pd_tempoatbarget any tempo applying at the start of the given bar EXPORT enum sscore_error sscore_pd_tempoatbar( const sscore *sc, int barindex, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no tempo value defined Discussionthis returns in tempo a) any metronome value or b) any sound tempo value defined at the start of the given bar sscore_pd_tempoatstartget any tempo applying at the start of the score EXPORT enum sscore_error sscore_pd_tempoatstart( const sscore *sc, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no tempo value defined Discussionthis returns in tempo a) any metronome value or b) any sound tempo value defined at the start of the score sscore_pd_timesigforbarget information about the notated time signature which applies to a bar EXPORT enum sscore_error sscore_pd_timesigforbar( const sscore *sc, int barindex, sscore_timesig *timesig); ParametersReturn Valueany error sscore_pd_updatetempowarning of user tempo change EXPORT void sscore_pd_updatetempo( sscore_playdata *pd); ParametersTypedefs
get_user_tempo_scalingdefine realtime user tempo specification typedef struct sscore_pd_usertempo { sscore_pd_int_fn get_user_bpm; sscore_pd_float_fn get_user_tempo_scaling; void *context; unsigned dummy[8]; } sscore_pd_usertempo; ParametersReturn Valuea scaling value defined by the user to multiply tempo values specified in the score sscore_barbeatsnumber and duration of beats in a bar typedef struct sscore_pd_barbeats { int beatsinbar; int beattime; // ms } sscore_pd_barbeats; See Also sscore_pd_bar_iteratorprivate bar iterator for accessing bars in correct sequence when playing typedef struct sscore_pd_bar_iterator { // private fields const sscore_playdata *pd; int idx; unsigned dummy[8]; } sscore_pd_bar_iterator; Discussionthis is not multi-thread safe. ie all functions using this must be called on a single thread sscore_pd_barbeatsnumber and duration of beats in a bar typedef struct sscore_pd_barbeats { int beatsinbar; int beattime; // ms } sscore_pd_barbeats; See Also sscore_pd_barnotes_iteratorprivate bar notes iterator for playing typedef struct sscore_pd_barnotes_iterator { // private fields sscore_pd_bar_iterator bi; int pidx; int nidx; unsigned dummy[8]; } sscore_pd_barnotes_iterator; Discussionthis provides notes sequentially with non-decreasing start time from the start of the bar to the end of the _following_ bar, ie notes in 2 bars, so that there is not an inter-bar discontinuity when using non-bar-aligned buffers NB This must be used with the supplied functions. The private fields should not be tampered with sscore_pd_notemidi-type information about a note for playing typedef struct sscore_pd_note { int midipitch; // 60 = C4. 0 = unpitched (eg percussion) int startbarindex; // index of bar in which this note starts (may be tied) int start; // start time from start of bar (milliseconds) int duration; // (ms) may be longer than a bar if tied int dynamic; // [0..100] value of the last dynamic enum sscore_pd_grace_e grace; // set for grace note sscore_item_handle item_h; // item handle used in sscore_contents unsigned dummy[8]; // future } sscore_pd_note; DiscussionNB The right-hand note of a tie is included in the duration of the left hand note and omitted from the list sscore_pd_notesampleinformation required for pre-loading a note sample typedef struct sscore_pd_notesample { int midipitch; // 60 = C4. 0 = unpitched (eg percussion) int duration; // (ms) may be longer than a bar if tied unsigned dummy[2]; } sscore_pd_notesample; sscore_pd_notesamplesinformation required for pre-loading note samples typedef struct sscore_pd_notesamples { int num; sscore_pd_notesample samples[sscore_pd_MaxNoteSamples]; unsigned dummy[8]; } sscore_pd_notesamples; sscore_pd_partsetdefine playing parts typedef struct sscore_pd_partset { int num; // the number of parts bool parts[sscore_kMaxParts]; // play value per part } sscore_pd_partset; sscore_pd_tempotempo information typedef struct sscore_pd_tempo { int bpm; int beattype; bool dot; bool usebeattype; // set if this is a beat type from a metronome mark and should be displayed, else it is a standard 4 for a sound tempo and is irrelevant to the beat unsigned dummy[8]; } sscore_pd_tempo; Enumerated Types
sscore_bartype_ecategorise partial bars enum sscore_bartype_e { sscore_bartype_full_bar, // normal full bar sscore_bartype_partial_first_bar, // partial bar is first bar in score (ie anacrusis) sscore_bartype_partial_bar_start, // partial bar including beat 1 (ie before repeat mark) sscore_bartype_partial_bar_end, // partial bar missing beat 1 (ie after repeat mark) sscore_bartype_default // for default argument }; Macro Definitions
sscore_pd_kAfterEndBarIndexspecial value to indicate beyond the last bar in the piece #define sscore_pd_kAfterEndBarIndex Value 0x7fffffff (2147483647) |