GUIDOLib  1.7.7
A Music Score Rendering Engine
Functions
Building abstract and graphic representations

Functions

GuidoErrCode GuidoInit (GuidoInitDesc *desc)
 
GuidoErrCode GuidoInitWithIndependentSVG ()
 
void GuidoShutdown ()
 
GuidoErrCode GuidoParseFile (const char *filename, ARHandler *ar) GUIDOAPI_deprecated
 
GuidoErrCode GuidoParseString (const char *str, ARHandler *ar) GUIDOAPI_deprecated
 
GuidoErrCode GuidoAR2GR (ARHandler ar, const GuidoLayoutSettings *settings, GRHandler *gr)
 
GRHandler GuidoAR2GRParameterized (ARHandler ar, const GuidoGrParameters *gp)
 GuidoAR2GRParameterized. Transforms a Guido abstract representation into a Guido graphic representation. It use given GuidoGrParameters with a layout settings and a page format. If a page format is used in gmn code, it has priority over the GuidoGrParameters's page format. More...
 
GuidoErrCode GuidoUpdateGR (GRHandler gr, const GuidoLayoutSettings *settings)
 
GuidoErrCode GuidoShowElement (GRHandler gr, GRElement elt, bool status)
 
float GuidoGetNotesDensity (GRHandler gr)
 
GuidoErrCode GuidoUpdateGRParameterized (GRHandler gr, const GuidoGrParameters *settings)
 
void GuidoFreeAR (ARHandler ar)
 
void GuidoFreeGR (GRHandler gr)
 
const char * GuidoGetErrorString (GuidoErrCode errCode)
 
int GuidoGetParseErrorLine () GUIDOAPI_deprecated
 
void GuidoGetDefaultLayoutSettings (GuidoLayoutSettings *settings)
 

Detailed Description

The Guido Engine operates on two kinds of music representation:

The functions described in this section are intended to build abstract and graphic representations.

Function Documentation

◆ GuidoAR2GR()

GuidoErrCode GuidoAR2GR ( ARHandler  ar,
const GuidoLayoutSettings settings,
GRHandler gr 
)

Transforms a Guido abstract representation into a Guido graphic representation. The engine applies layout algorithms according to the settings given as argument.

Parameters
arthe handler to the abstract representation.
settingsa pointer to the settings for the graphic layout. If null, default settings are applied.
gron output: a Guido opaque handle to a graphic music representation It's the caller responsability to free the handle using GuidoFreeGR.
Returns
a Guido error code.

◆ GuidoAR2GRParameterized()

GRHandler GuidoAR2GRParameterized ( ARHandler  ar,
const GuidoGrParameters gp 
)

GuidoAR2GRParameterized. Transforms a Guido abstract representation into a Guido graphic representation. It use given GuidoGrParameters with a layout settings and a page format. If a page format is used in gmn code, it has priority over the GuidoGrParameters's page format.

Parameters
ara Abstract representation handler.
gpa GuidoGrParameters structure. If null default layout settings and page format are used.
Returns
a Graphic representation handler or null if an error occurs.

◆ GuidoFreeAR()

void GuidoFreeAR ( ARHandler  ar)

Releases a Guido abstract representation.

Parameters
arthe handler to the abstract representation.

◆ GuidoFreeGR()

void GuidoFreeGR ( GRHandler  gr)

Releases a Guido graphic representation.

Parameters
grthe handler to the graphic representation.

◆ GuidoGetDefaultLayoutSettings()

void GuidoGetDefaultLayoutSettings ( GuidoLayoutSettings settings)

Gives the default values of the layout settings.

Parameters
settingson output, a pointer to the settings to be filled with default values.

◆ GuidoGetErrorString()

const char* GuidoGetErrorString ( GuidoErrCode  errCode)

Gives a textual description of a Guido error code.

Parameters
errCodea Guido error code.
Returns
a string describing the error.

◆ GuidoGetNotesDensity()

float GuidoGetNotesDensity ( GRHandler  gr)

Gives the notes density.

The notes density is computed on the x axis only. It represents the ratio between the space occupied by the notes over each measure of each staff. The maximum density is retained over a single line.

Parameters
grthe handler to the graphic representation.
Returns
a floating point value that expresses the density as a percentage of the staves space.

◆ GuidoGetParseErrorLine()

int GuidoGetParseErrorLine ( )

Gives the line of a Guido script where the last parse error has occured.

Returns
a line number.

◆ GuidoInit()

GuidoErrCode GuidoInit ( GuidoInitDesc desc)

Initialises the Guido Engine. Must be called before any attempt to read a Guido file or to use the Guido Factory

Parameters
descthe graphic environment description.
Returns
a Guido error code.

WARNING: the caller must ensure desc maintains a constant reference on a valid VGDevice, because Guido keeps it internally (to calculate fonts, etc.)

◆ GuidoInitWithIndependentSVG()

GuidoErrCode GuidoInitWithIndependentSVG ( )

Initialises the Guido Engine with an independent SVG device, avoiding the need to pass a description. Useful for contexts (like javascript) where structures cannot be easily manipulated.

◆ GuidoParseFile()

GuidoErrCode GuidoParseFile ( const char *  filename,
ARHandler ar 
)

Parses a Guido Music Notation (.gmn) file and builds the corresponding abstract representation.

Parameters
filenamethe file to parse.
aron output: a Guido opaque handle to an abstract music representation. It's the caller responsability to free the handle using GuidoFreeAR.
Returns
a Guido error code.

◆ GuidoParseString()

GuidoErrCode GuidoParseString ( const char *  str,
ARHandler ar 
)

Parses a buffer and builds the corresponding abstract representation. The buffer if expected to contain gmn code.

Parameters
strthe null terminated buffer to parse.
aron output: a Guido opaque handle to an abstract music representation. It's the caller responsability to free the handle using GuidoFreeAR.
Returns
a Guido error code.

◆ GuidoShowElement()

GuidoErrCode GuidoShowElement ( GRHandler  gr,
GRElement  elt,
bool  status 
)

Show or hide notation elements.

Parameters
grthe handler to the graphic representation.
eltthe target element
statusa boolean value to show (true) or hide (false) the target element
Returns
a Guido error code.

◆ GuidoShutdown()

void GuidoShutdown ( )

Guido Engine shutdown

Actually release the font allocated by the engine. Anyway, the fonts are release when the client application exit but the function provides control over the time of the release.

◆ GuidoUpdateGR()

GuidoErrCode GuidoUpdateGR ( GRHandler  gr,
const GuidoLayoutSettings settings 
)

Applies new layout settings to an existing Guido graphic representation.

Parameters
grthe handler to the graphic representation.
settingsa pointer to the settings for the graphic layout. If null, default settings are applied.
Returns
a Guido error code.

◆ GuidoUpdateGRParameterized()

GuidoErrCode GuidoUpdateGRParameterized ( GRHandler  gr,
const GuidoGrParameters settings 
)

Applies new layout settings and page format to an existing Guido graphic representation.

Parameters
grthe handler to the graphic representation.
settingsa pointer to the settings for the graphic representation. If null, default settings are applied.
Returns
a Guido error code.

Guido Project Copyright © 2019 Grame-CNCM