sscore.h
IntroductionThe base C interface to SeeScoreLib This interface provides functions to read a MusicXML file and create a score layout consisting
of a set of systems to be displayed one above the next. Important Types:
Important Functions:
Coordinates: In all coordinates x increases to the left and y increases downwards Bar indices: The first bar in the score has always index 0, and the bars are indexed sequentially to the end. System indices: The top system has index 0, and other systems are indexed sequentially downwards. Thread Info: All functions in this interface must be called from a single thread (probably the main thread)
EXCEPT for sscore_layout. C Pseudoclasses
GroupsGeneral utility FunctionsGroup members:
The sscore_system interfacefunctions accessing the system - a range of bars and parts to display in a rectangle Group members:
The sscore_systemlist interfacefunctions to access a simple list of system Group members:
The main sscore interfaceobtain information about the score Group members:
Functions
sscore_abbrevpartnameforpartreturn the abbreviated partname for the part EXPORT const char *sscore_abbrevpartnameforpart( const sscore *sc, int partindex); ParametersReturn Valuepointer to char NULL-terminated C-style string sscore_barnumberforindexreturn the number of the bar for the given bar index [0..numbars-1] EXPORT const char *sscore_barnumberforindex( const sscore *sc, int barindex); ParametersReturn Valuethe (string) bar number sscore_blackEXPORT sscore_colour_alpha sscore_black(); Return Valueblack colour sscore_compressxmlconvert xml file to mxl EXPORT bool sscore_compressxml( const char *xmlfilepath, const char *dest_path, char *mxlfilename, int fnsize); ParametersReturn Valuetrue if success sscore_decompressmxlconvert mxl file to xml EXPORT bool sscore_decompressmxl( const char *mxlfilepath, const char *dest_path, char *xmlfilename, int fnsize); ParametersReturn Valuereturn true if success sscore_defaultfontnamefortextthe name of the font that will be registered by default for the text type EXPORT const char *sscore_defaultfontnamefortext( enum sscore_texttype text); ParametersReturn Valuethe (platform-dependent) font name which will be used by default for the text type if it is not overridden using sscore_setfontnamefortext sscore_disposefree the score memory, and any undisposed systems EXPORT void sscore_dispose( sscore *sc); Parameterssscore_extractfilesectionextract a section of a text file around a given line number into a buffer EXPORT int sscore_extractfilesection( const char *filepath, int line, int numlines, char *buffer, int buffersize); ParametersReturn Valuethe number of bytes added to the buffer Discussionuseful for displaying a section of an XML file around a given line where there is an error sscore_fontnamefortextget the registered font name for a text type EXPORT const char *sscore_fontnamefortext( enum sscore_texttype text); ParametersReturn Valuethe (platform-dependent) font name which will be used for the text type sscore_fullpartnameforpartreturn the partname for the part EXPORT const char *sscore_fullpartnameforpart( const sscore *sc, int partindex); ParametersReturn Valuepointer to char NULL-terminated C-style string sscore_getheaderget the xml score-header information EXPORT void sscore_getheader( const sscore *sc, sscore_header *header); ParametersDiscussionNB The returned pointers inside header are owned by sc. The caller should copy any required data sscore_getversionreturn the version number of the library EXPORT sscore_version sscore_getversion(); sscore_instrumentnameforpartreturn the first non-empty instrument name for the part EXPORT const char *sscore_instrumentnameforpart( const sscore *sc, int partindex); ParametersReturn Valuepointer to char NULL-terminated C-style string sscore_ismodifiedtest for changed score eg to determine whether to save EXPORT bool sscore_ismodified( const sscore *sc); ParametersReturn Valuetrue if score is modified sscore_layoutlayout a set of systems and return them through a callback function EXPORT enum sscore_error sscore_layout( sscore *sc, sscore_graphics *graphics, float width, float max_system_height, const bool *parts, sscore_layout_callback_fn cb, void *arg, float magnification, const sscore_layoutoptions *opt); Parameters
Return Valueany error DiscussionThis should be called on a background thread and it will call cb for each system laid out, from top to bottom. cb will normally add the system to a sscore_systemlist on the foreground (gui event dispatch) thread. systems are stored in sc as they are produced sscore_layout1systemlayout a single system with a single part. EXPORT sscore_system *sscore_layout1system( sscore *sc, sscore_graphics *graphics, int startbarindex, float width, float max_height, int partindex, float magnification, const sscore_layoutoptions *opt, int maxBars); Parameters
Return Valuethe system Discussionuseful for display of a single part for part selection sscore_loadheaderfromfileload only some header metadata quickly from file without loading the rest of the score EXPORT bool sscore_loadheaderfromfile( const char *filepath, sscore_miniheader *header); ParametersReturn Valuetrue if succeeded Discussionthis is much quicker than loading the whole score and reading the header from that, and is suitable for presenting file metadata, title, composer etc in a list of MusicXML files. sscore_loadxmldataload in-memory xml or mxl data and return score EXPORT sscore *sscore_loadxmldata( const char *data, int len, const sscore_loadoptions *opt, sscore_loaderror *err); ParametersReturn Valuethe score sscore_loadxmlfileload xml or mxl file and return score EXPORT sscore *sscore_loadxmlfile( const char *filepath, const sscore_loadoptions *opt, sscore_loaderror *err); ParametersReturn Valuethe score sscore_numbarsreturn the total number of bars in the score EXPORT int sscore_numbars( const sscore *sc); ParametersReturn Valuethe number of bars in the score sscore_numpartsreturn the number of parts in the score EXPORT int sscore_numparts( const sscore *sc); ParametersReturn Valuethe number of parts in the score sscore_numstavesforpartreturn the number of staves for the part EXPORT int sscore_numstavesforpart( const sscore *sc, int partindex); ParametersReturn Valuethe number of staves in this part (1..2) sscore_savefilesave the score to a file EXPORT enum sscore_error sscore_savefile( sscore *sc, const char *filepath, enum sscore_savetype savetype); ParametersReturn Valueany error sscore_setfontnamefortextset the registered font name for a text type EXPORT void sscore_setfontnamefortext( enum sscore_texttype text, const char *fontname); Parameterssscore_stringforelementtypeget a string for enum sscore_element_type EXPORT const char *sscore_stringforelementtype( enum sscore_element_type tp); sscore_system_barindexforxposreturn the bar index for a x-coord in the system EXPORT int sscore_system_barindexforxpos( const sscore_system *sys, float xpos); ParametersReturn Valuethe bar index in the system containing this x coord, or -1 if outside the system sscore_system_boundsreturn the bounding box of the system EXPORT sscore_size sscore_system_bounds( const sscore_system *sys); ParametersReturn Valuethe size of the system sscore_system_defaultspacingreturn a default system spacing EXPORT float sscore_system_defaultspacing( const sscore_system *sys); ParametersReturn Valuethe default inter-system spacing sscore_system_drawdraw the system at the given point EXPORT void sscore_system_draw( sscore_graphics *graphics, const sscore_system *sys, const sscore_point *tl, float magnification); Parameterssscore_system_getbarlayoutreturn information (in result) about the dimensions of the barlines in a part EXPORT sscore_barlayout sscore_system_getbarlayout( const sscore_system *sys, int partindex); ParametersReturn Valuethe bar layout information sscore_system_getcursorrectreturn the cursor rectangle for a particular system and bar EXPORT sscore_cursor sscore_system_getcursorrect( sscore_graphics *graphics, const sscore_system *sys, int barIndex); ParametersReturn Valuethe cursor info sscore_system_getstafflayoutreturn information (in result) about the dimensions of the staves in a part EXPORT sscore_stafflayout sscore_system_getstafflayout( const sscore_system *sys, int partindex); ParametersReturn Valuethe staff layout information sscore_system_includesbarreturn true if this system includes the given bar index EXPORT bool sscore_system_includesbar( const sscore_system *sys, int barindex); ParametersReturn Valuereturn true if this system includes the given bar index sscore_system_indexreturn the index (from the top of the score) of the system EXPORT int sscore_system_index( const sscore_system *sys); ParametersReturn Valuethe index of the system sscore_system_magnificationreturn the default magnification at which the system will be drawn EXPORT float sscore_system_magnification( const sscore_system *sys); ParametersReturn Valuethe magnification - 1.0 is a close approximation to a standard printed score with 6mm staff height sscore_system_magnifymagnify the single system with a single part EXPORT sscore_system *sscore_system_magnify( sscore *sc, const sscore_system *sys, int partIndex); ParametersReturn Valuea new magnified system sscore_system_numbarsreturn the start bar index and number of bars for the given system EXPORT sscore_barrange sscore_system_numbars( const sscore_system *sys); ParametersReturn Valuethe start bar and number of bars in the system sscore_system_partindexforyposreturn the part index for a y-coord in the system EXPORT int sscore_system_partindexforypos( const sscore_system *sys, float ypos); ParametersReturn Valuethe part index in the system containing this y coord sscore_system_pointstofontsizeEXPORT float sscore_system_pointstofontsize( const sscore_system *sys, float points); Parameterssscore_system_printdraw the system at the given point optimised for printing or pdf generation EXPORT void sscore_system_print( sscore_graphics *graphics, const sscore_system *sys, const sscore_point *tl, float magnification); Parameterssscore_system_releasedecrement the retain count of the system EXPORT void sscore_system_release( sscore *sc, sscore_system *sys); ParametersDiscussionThe caller must release the system when it release its pointer sscore_system_retainincrement the retain count of the system EXPORT void sscore_system_retain( sscore *sc, sscore_system *sys); ParametersDiscussionThe caller must retain the system when it stores its pointer sscore_system_staff_bottom_yposreturn bottom ypos of the staff in the part EXPORT float sscore_system_staff_bottom_ypos( const sscore_system *sys, int partIndex, int staffIndex); ParametersReturn Valuethe distance from the top of the system to the bottom line of the given staff sscore_system_staff_heightreturn the height of the staff in the part EXPORT float sscore_system_staff_height( const sscore_system *sys, int partIndex, int staffIndex); ParametersReturn Valuethe height of the staff from the bottom line to the top line sscore_system_staffindexforyposreturn the nearest staff index for a y-coord in the system/part EXPORT int sscore_system_staffindexforypos( const sscore_system *sys, int partindex, float ypos); ParametersReturn Valuethe 0-based index of the closest staff in the system/part containing this y coord sscore_system_stafflocationforyposis a y-location above or below the staff returned by sscore_system_staffindexforypos EXPORT enum sscore_system_stafflocation_e sscore_system_stafflocationforypos( const sscore_system *sys, int partindex, int staffindex, float ypos); ParametersReturn Valuethe above/instaff/below location relative to the staff sscore_systemlist_addadd a system to the end of ss EXPORT void sscore_systemlist_add( sscore_systemlist *ss, sscore_system *sys); ParametersDiscussionusually called from sscore_layout_callback_fn. sys retain count is incremented sscore_systemlist_atget a system by index EXPORT sscore_system *sscore_systemlist_at( const sscore_systemlist *ss, int sysindex); ParametersReturn Valuethe system in the systemlist indexed by sysindex (indexed in order of add) sscore_systemlist_boundsreturn the bounds of the score EXPORT sscore_size sscore_systemlist_bounds( const sscore_systemlist *ss, float systemspacing); ParametersReturn Valuethe (width,height) of the score with the given systemspacing sscore_systemlist_clearclear all sytems from the list EXPORT void sscore_systemlist_clear( sscore *sc, sscore_systemlist *ss); Parameterssscore_systemlist_createcreate a new sscore_systemlist EXPORT sscore_systemlist *sscore_systemlist_create(); Return Valuethe new sscore_systemlist Discussionthe returned value should be disposed with sscore_systemlist_dispose sscore_systemlist_defaultspacingreturn the default inter-system spacing EXPORT float sscore_systemlist_defaultspacing( const sscore_systemlist *ss); ParametersReturn Valuethe default inter-system spacing sscore_systemlist_disposeclear all systems from the list and dispose it EXPORT void sscore_systemlist_dispose( sscore *sc, sscore_systemlist *ss); ParametersDiscussionIf any system is still retained (may need to await completion on other threads) it will be deleted on disposal of sscore sscore_systemlist_sizereturn the number of systems held in ss EXPORT int sscore_systemlist_size( const sscore_systemlist *ss); ParametersReturn Valuethe number of systems held in ss sscore_systemlist_sysforbarreturn the system index for the bar index in the systemlist EXPORT int sscore_systemlist_sysforbar( const sscore_systemlist *ss, int barindex); ParametersReturn Valuereturn the system index for the bar index, or -1 if barindex invalid sscore_unionrectreturn the union of 2 rectangles EXPORT sscore_rect sscore_unionrect( const sscore_rect *r1, const sscore_rect *r2); ParametersReturn Valuethe rectangular union of r1 and r2 sscore_updateheaderchange the xml score-header information EXPORT void sscore_updateheader( sscore *sc, enum sscore_header_fieldid hid, const char *val); ParametersTypedefs
sscore_barlayoutbarline measurement information returned from sscore_system_getbarlayout typedef struct sscore_barlayout { int partindex; // the 0-based index of the part increasing from the top int numbarlines; // number in barline array, 0 if part not displayed struct { int barindex; enum sscore_barlineloc_e loc; // all normal default barlines are left, except system right sscore_rect rect; // a rectangle enclosing the barline unsigned dummy[32];//unused } barline[sscore_kMaxBarlinesInSystemPart]; unsigned dummy[128];//unused } sscore_barlayout; sscore_barrangethe range of bars in a system from sscore_system_numbars typedef struct sscore_barrange { int startbarindex; int numbars; }sscore_barrange; sscore_coloura colour typedef struct sscore_colour { float r,g,b; } sscore_colour; sscore_colour_alphaa colour with alpha (opacity) typedef struct sscore_colour_alpha { float r,g,b,a; } sscore_colour_alpha; sscore_cursorinformation about the cursor from sscore_system_getcursorrect typedef struct sscore_cursor { bool bar_in_system; sscore_rect rect; } sscore_cursor; sscore_headerinformation in the score-header element of the xml file typedef struct sscore_header { const char *work_number; const char *work_title; const char *movement_number; const char *movement_title; const char *composer; const char *lyricist; const char *arranger; int num_credits; struct { const char *credit_words; } credits[sscore_kMaxCredits]; int num_parts; struct { const char *name; const char *abbrev; } parts[sscore_kMaxParts]; }sscore_header; Discussionall are null-terminated c-style strings or 0 sscore_item_handlea unique handle for an item (note,rest,clef etc) in the score typedef unsigned long sscore_item_handle; sscore_layout_callback_fnThe type of a callback called from sscore_layout typedef bool ( *sscore_layout_callback_fn)( sscore_system *sys, void *arg); ParametersDiscussionThe callback is called by sscore_layout on a background thread for each system when it is laid out. This allows the ui to update while the layout is in progress The callback returns false to abort the layout, else true. sscore_layoutoptionsoptions for sscore_layout typedef struct sscore_layoutoptions { bool hidepartnames; // set this so that part names are not displayed in the layout bool hidebarnumbers; // set this so that bar numbers are not displayed unsigned flags; // bit flags defined in enum sscore_layoutOptionsFlagBits. default set 0. unsigned dummy[15]; // for future. set to zero } sscore_layoutoptions; sscore_libkeytypea key obtained from Dolphin Computing for unlocking the SeeScoreLib capabilities typedef struct sscore_libkeytype { const char *identity; // C-style string associated with the application using the SeeScoreLib unsigned capabilities[sscore_kNumCapabilityWords]; // encoded capabilities for this identity unsigned key[sscore_kNumKeyWords]; // key associated with identity and capabilities } sscore_libkeytype; sscore_loaderrora description of any error or warnings from sscore_load typedef struct sscore_loaderror { enum sscore_error err; // any error on load int line; // line in the xml file of the (first) error (0 if none) int col; // file column in the line (0 if none) char text[sscore_kMaxErrorTextChars]; // any more information on the error int numwarnings; // the number of warnings struct { enum sscore_warning w; // a warning value int partindex; // -1 for all parts int barindex; // -1 for all bars enum sscore_element_type element; unsigned dummy; // for future } warn[sscore_kMaxWarnings]; // any warnings on load unsigned dummy[16]; // for future } sscore_loaderror; sscore_loadoptionsoptions for sscore_load typedef struct sscore_loadoptions { const sscore_libkeytype *key; // use NULL for evaluation of SeeScoreLib bool compressed; unsigned flags; // bit set of sscore_loadopt_flagbits unsigned dummy[15]; // for future. set to zero } sscore_loadoptions; sscore_miniheaderinformation in the score-header element of the xml file typedef struct sscore_miniheader { char work_number[sscore_kMiniHeaderNumberSize]; char work_title[sscore_kMiniHeaderStringSize]; char movement_number[sscore_kMiniHeaderNumberSize]; char movement_title[sscore_kMiniHeaderStringSize]; char composer[sscore_kMiniHeaderStringSize]; char lyricist[sscore_kMiniHeaderStringSize]; char arranger[sscore_kMiniHeaderStringSize]; int num_credits; struct { char credit_words[sscore_kMiniHeaderStringSize]; } credits[sscore_kMiniHeaderMaxCredits]; int num_parts; struct { char name[sscore_kMiniHeaderPartNameSize]; } parts[sscore_kMiniHeaderMaxParts]; }sscore_miniheader; Discussionall space in this struct is allocated by the client and strings are copied into this for quick read of file header and no explicit dealloc sscore_partlayoutpart staff measurement information returned from sscore_system_getstafflayout typedef struct sscore_stafflayout { int partindex; // the 0-based index of the part increasing from the top float tenth_size; // the size in OS graphics units of one tenth of a staff line spacing (ie one 50th of the height of a 4-line staff) int numstaves; // the number of staves in this system (usually 1 or 2) and the number of valid entries in the staff array struct { sscore_rect rect; // a rectangle defined by the left of the top staff line and the right of the bottom staff line (height = 0 if part not displayed) int numlines; // the number of lines in the staff, 0 if this part is not displayed unsigned dummy[32];//unused } staff[sscore_kMaxStavesInPart]; unsigned dummy[128];//unused } sscore_stafflayout; See Also sscore_pointa point typedef struct sscore_point { float x,y; } sscore_point; sscore_rectcoords for a rectangle typedef struct sscore_rect { float xorigin,yorigin,width,height; } sscore_rect; sscore_sizea size typedef struct sscore_size { float width,height; } sscore_size; sscore_stafflayoutpart staff measurement information returned from sscore_system_getstafflayout typedef struct sscore_stafflayout { int partindex; // the 0-based index of the part increasing from the top float tenth_size; // the size in OS graphics units of one tenth of a staff line spacing (ie one 50th of the height of a 4-line staff) int numstaves; // the number of staves in this system (usually 1 or 2) and the number of valid entries in the staff array struct { sscore_rect rect; // a rectangle defined by the left of the top staff line and the right of the bottom staff line (height = 0 if part not displayed) int numlines; // the number of lines in the staff, 0 if this part is not displayed unsigned dummy[32];//unused } staff[sscore_kMaxStavesInPart]; unsigned dummy[128];//unused } sscore_stafflayout; See Also sscore_timesiga conventional time signature typedef struct sscore_timesig { int numbeats; // number of beats in bar int beattype; // 8 = quaver; 4 = crochet; 2 = minim etc } sscore_timesig; sscore_versiona version number typedef struct sscore_version { int major; int minor; } sscore_version; Enumerated Types
sscore_element_typeelement type for warning enum sscore_element_type { sscore_element_none, sscore_element_beam, sscore_element_slur, sscore_element_tied, sscore_element_lyric, sscore_element_bracket, sscore_element_tuplet, sscore_element_slide, sscore_element_glissando, sscore_element_wedge, sscore_element_dashes, sscore_element_pedal, sscore_element_octave_shift, sscore_element_principal_voice, sscore_element_part, sscore_element_accidental, sscore_element_stem, sscore_element_tremolo, sscore_element_unknown }; sscore_errorall errors enum sscore_error { sscore_NoError = 0, sscore_OutOfMemoryError, sscore_FileOpenFailedError, sscore_XMLValidationError, sscore_NoBarsInFileError, sscore_WidthTooSmallError, sscore_NullGraphicsError, sscore_MagnificationTooSmallError, sscore_MagnificationTooLargeError, sscore_NoPartsError, sscore_NoPartsToDisplayError, sscore_UnknownError, sscore_BadHeightError, sscore_WidthTooLargeForIphoneError, // the system width is limited on the iPhone-only licensed framework sscore_HeightTooLargeForIphoneError, // the system height is limited on the iPhone-only licensed framework sscore_NullScoreError, sscore_NoBufferError, // the buffer point supplied to a function is NULL or the buffersize is too small sscore_BadPartIndexError, sscore_BadBarIndexError, sscore_UnlicensedFunctionError, // a function has been called with an invalid license sscore_NoImplError, // a function or feature is not currently implemented sscore_InternalFault, sscore_ItemNotFoundError, sscore_ArgumentError, sscore_SoundSampleLoadFailedError, sscore_SoundSetupFailedError, sscore_SynthStartFailedError, sscore_SynthNoInstrumentsError, // addInstrument was not called sscore_SynthNoPlayData, // synth not called setup before start sscore_WrongTimingBarCountError,// sscore_pd_timing struct contains too few bars defined sscore_SaveFailed }; sscore_layoutOptionsFlagBitsbit flags for layout options flags field enum sscore_layoutOptionsFlagBits { sscore_simplifyHarmonyEnharmonicSpelling_bit = 0x01, // set this flag so F-double-sharp appears in a harmony as G sscore_layoutopt_ignorexmlpositions_bit = 0x02, // set this flag to ignore default-x,default-y,relative-x,relative-y positions sscore_layoutopt_expandrepeat_bit = 0x04, // not yet implemented sscore_layoutopt_editmode_bit = 0x08, // set for edit mode increased staff spacings sscore_layoutopt_heedXMLxLayout_bit = 0x10, // set to use any XML-defined x layout information (default-x in notes and measure widths) sscore_layoutopt_redbeyondbarend_bit = 0x10000 // set to display notes in red if they are beyond the end of the bar as defined by the time signature }; sscore_loadopt_flagbitsflag bits for load enum sscore_loadopt_flagbits { sscore_loadopt_checkxml_bit = 1, // when set various logical tests will be performed after loading and results reported as warnings sscore_loadopt_generatebeams_bit = 2 }; sscore_savetypesave compressed or uncompressed enum sscore_savetype { sscore_savetype_uncompressed, sscore_savetype_compressed, sscore_savetype_default // use this to save as same type as source file (if there is a source file), else compressed }; sscore_system_stafflocation_edefine vertical location relative to the staff enum sscore_system_stafflocation_e { sscore_system_staffloc_undefined, sscore_system_staffloc_above, sscore_system_staffloc_instaff, sscore_system_staffloc_below }; sscore_texttypetype of text determining preset font to use enum sscore_texttype { sscore_lyricText, // to define font for lyrics sscore_directionText, // ..directions sscore_metronomeText, // ..metronome marking sscore_barNumberText, // ..bar numbers sscore_repeatBarText, // ..repeat bar text sscore_octaveShiftText, // ..octave shift sscore_slideText, // text over slide sscore_tupletText, // .. text over tuplets sscore_harmonyText, // ..harmony text sscore_harmonyFrameText, // .. guitar frame text sscore_tabStaffText, // ..tab staff text sscore_fingeringText, // .. fingering text sscore_rehearsalText, // ..rehearsal marking text (eg A,B etc) sscore_partNameText, // .. part name text sscore_partGroupNameText // .. part group name text }; sscore_warningall warnings enum sscore_warning { sscore_warning_none, sscore_warning_missingelement, // <accidental> or <stem> elements are not defined in the file and will be reconstructed by SeeScore sscore_warning_measurecount, // different parts do not have the same number of measures sscore_warning_beamcount, // a note has the wrong number of beams defined for the note type sscore_warning_consistency, // an error in ordering of beam,slur,tied,tuplet begin/start,continue,end/stop sscore_warning_unexpectedStart, // beam/slur/tie/tuplet.. 2nd start sscore_warning_unexpectedContinue, // beam/slur continue without start sscore_warning_unexpectedStop, // beam/slur/tie/tuplet stop without start sscore_warning_unclosed, // beam/slur/tied/tuplet unclosed at end of score/measure sscore_warning_unpaired, // half of paired type (start/stop) is missing or extra sscore_warning_badlevel // level number is > 6 }; |