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
GroupsThe sscore_systemlist interfacefunctions to access a simple list of system Group members:
The main sscore interfaceobtain information about the score Group members:
General utility FunctionsGroup members:
The sscore_system interfacefunctions accessing the system - a range of bars and parts to display in a rectangle 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_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_disposefree the score memory, and any undisposed systems EXPORT void sscore_dispose( sscore *sc); Parameterssscore_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_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); Parameters
Return Valuethe system Discussionuseful for display of a single part for part selection 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); Parameterssscore_loadxmlfileload xml or mxl file and return score EXPORT sscore *sscore_loadxmlfile( const char *filepath, const sscore_loadoptions *opt, sscore_loaderror *err); Parameterssscore_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_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_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_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_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_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_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 Typedefs
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; const char *credit_words[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_keya 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; See Also 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; Discussionsscore_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; See Also 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 unsigned dummy[4]; // 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 dummy[16]; // for future. set to zero } sscore_loadoptions; 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_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_errorall errors enum sscore_error { sscore_NoError = 0, sscore_OutOfMemoryError, 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_layoutOptionsFlagBitsbit flags for layout options flags field NB This value is the bit shift for the flag enum sscore_layoutOptionsFlagBits { sscore_simplifyHarmonyEnharmonicSpelling // set this flag so F-double-sharp appears in a harmony as G }; sscore_warningall warnings enum sscore_warning { sscore_NoWarning, sscore_MissingAccidentalsWarning // the xml file is missing required accidental elements which will be reconstructed }; |