#include <lomse_drawer.h>

Detailed Description

Drawer is an abstract base class for any drawer object. A drawer is responsible for transforming drawing commands into something understandable by the underlying rendering engine (e.g.: a bitmap, svg file, paths, etc.), to display the sheet music.

The Drawer class is equivalent to the drawing interfaces present the operating systems' graphics libraries, for example macOS' “Quartz”, Linux X Window System's “Xlib/XCB” or the Microsoft Windows API “Device Context” (DC) that is part of the “Graphics Device Interface” (GDI).

As Lomse aims to be platform independent, it does not use any platform specific graphics interface. Instead it was decided to create an abstract interface class: Drawer. This solution allows any user application to implement its own drawer classes and do all drawing natively without having to use the BitmapDrawer class implemented by Lomse.

The interface of Drawer class mimics SVG commands.

Public Member Functions
	Drawer (LibraryScope &libraryScope)

virtual	~Drawer ()

SVG path commands
Methods to define a path and all its commands.
virtual void	begin_path ()=0

virtual void	end_path ()=0

virtual void	close_path ()=0

virtual void	add_path (VertexSource &vs, unsigned path_id=0, bool solid_path=true)=0

virtual void	move_to (double x, double y)=0

virtual void	move_to_rel (double x, double y)=0

virtual void	line_to (double x, double y)=0

virtual void	line_to_rel (double x, double y)=0

virtual void	hline_to (double x)=0

virtual void	hline_to_rel (double x)=0

virtual void	vline_to (double y)=0

virtual void	vline_to_rel (double y)=0

virtual void	quadratic_bezier (double x1, double y1, double x, double y)=0

virtual void	quadratic_bezier_rel (double x1, double y1, double x, double y)=0

virtual void	quadratic_bezier (double x, double y)=0

virtual void	quadratic_bezier_rel (double x, double y)=0

virtual void	cubic_bezier (double x1, double y1, double x2, double y2, double x, double y)=0

virtual void	cubic_bezier_rel (double x1, double y1, double x2, double y2, double x, double y)=0

virtual void	cubic_bezier (double x2, double y2, double x, double y)=0

virtual void	cubic_bezier_rel (double x2, double y2, double x, double y)=0

SVG basic shapes commands
Methods to draw elements defined by some combination of straight lines and curves. Specifically: ‘circle’, ‘line’, ‘path’, ‘polygon’, and ‘rect’. Using these methods requires first to invoque begin_path(), as well as to define the desired attributes by invoking attribute setting methods (e.g. fill(), stroke(), ...). And finally closing the path close_path().
virtual void	rect (UPoint pos, USize size, LUnits radius)=0

virtual void	circle (LUnits xCenter, LUnits yCenter, LUnits radius)=0

virtual void	line (LUnits x1, LUnits y1, LUnits x2, LUnits y2, LUnits width, ELineEdge nEdge=k_edge_normal)=0

virtual void	polygon (int n, UPoint points[])=0

virtual void	line_with_markers (UPoint start, UPoint end, LUnits width, ELineCap startCap, ELineCap endCap)=0

Attribute setting methods
Define the attributes for current open path.
virtual void	fill (Color color)=0

virtual void	fill_none ()=0

virtual void	stroke (Color color)=0

virtual void	stroke_none ()=0

virtual void	stroke_width (double w)=0

virtual void	gradient_color (Color c1, Color c2, double start, double stop)=0

virtual void	gradient_color (Color c1, double start, double stop)=0

virtual void	fill_linear_gradient (LUnits x1, LUnits y1, LUnits x2, LUnits y2)=0

Text redering methods
Are somehow equivalent to the "<text>" SVG element.
virtual bool	select_font (const std::string &language, const std::string &fontFile, const std::string &fontName, double height, bool fBold=false, bool fItalic=false)=0

virtual void	set_text_color (Color color)

virtual int	draw_text (double x, double y, const std::string &str)=0

virtual int	draw_text (double x, double y, const wstring &str)=0

virtual void	draw_glyph (double x, double y, unsigned int ch)=0

virtual void	draw_glyph_rotated (double x, double y, unsigned int ch, double rotation)=0

Render a bitmap
virtual void	draw_bitmap (RenderingBuffer &bmap, bool hasAlpha, Pixels srcX1, Pixels srcY1, Pixels srcX2, Pixels srcY2, LUnits dstX1, LUnits dstY1, LUnits dstX2, LUnits dstY2, EResamplingQuality resamplingMode, double alpha=1.0)=0

Drawer settings
Methods to render a bitmap. They are somehow equivalent to the "image" SVG element. The only one currently used by Lomse is draw_bitmap() and is used when the Document includes some JPG or PNG image.
virtual void	set_shift (LUnits x, LUnits y)=0

virtual void	remove_shift ()=0

virtual void	render ()=0

virtual void	set_affine_transformation (TransAffine &transform)=0

virtual void	reset (Color bgcolor)=0

Device <--> model units conversion
In Lomse, there are two types of coordinates: those defined in the device space, that is, the Drawer space (e.g. pixels) and those defined in the model space, that is, real world units (tenths of one millimeter).
virtual void	device_point_to_model (double x, double y) const =0

virtual void	model_point_to_device (double x, double y) const =0

virtual LUnits	device_units_to_model (double value) const =0

virtual double	model_to_device_units (LUnits value) const =0

Shapes info
These methods serve to provide the Drawer with information about the shapes it is drawing. This information is normally irrelevant but in some cases (e.g.SVG) it can be incorporated into the output if desired.
virtual void	start_simple_notation (std::string UNUSED(id), std::string UNUSED(classname))

virtual void	start_composite_notation (std::string UNUSED(id), std::string UNUSED(classname))

virtual void	end_composite_notation ()

Viewport info
Viewport is a concept related to the View, not to the Drawer. But for some Drawer implementations, this information can be required. For instance, the Drawer can speed up rendition if it knows the area that is currently visible, so that it can ignore non-visible areas. Therefore, the View always informs the Drawer when any change in the viewport. Received coordinates are in device units (e.g. Pixels).
virtual void	new_viewport_origin (double x, double y)

virtual void	new_viewport_size (double x, double y)

Other methods
virtual bool	is_ready () const =0

virtual bool	accepts_id_class () const

Constructor & Destructor Documentation

◆ Drawer()

Drawer::Drawer ( LibraryScope & libraryScope )

Constructor.

Parameters

libraryScope The library Scope object associated to this instance of the Lomse library. Can be obtained with method LomseDoorway::get_library_scope().

Attention: Once created and injected in a View, the ownership of the Drawer is passed to the View.

◆ ~Drawer()

virtual Drawer::~Drawer ( )

inlinevirtual

Destructor

Member Function Documentation

◆ accepts_id_class()

virtual bool Drawer::accepts_id_class ( ) const

inlinevirtual

Returns true if the Drawer accepts 'id' and 'class' information

◆ add_path()

virtual void Drawer::add_path	(	VertexSource &	vs,
		unsigned	path_id = `0`,
		bool	solid_path = `true`
	)

pure virtual

Creates a new path with its commands and points provided by the "VertexSource" parameter. It is similar to SVG "path" element.

◆ begin_path()

virtual void Drawer::begin_path ( )

pure virtual

Start a path. Equivalent to SVG start tag "<path ".

◆ circle()

virtual void Drawer::circle	(	LUnits	xCenter,
		LUnits	yCenter,
		LUnits	radius
	)

pure virtual

Draw a circle based on a center point and a radius. It is equivalent to the "circle" SVG element.

◆ close_path()

virtual void Drawer::close_path ( )

pure virtual

Close a sub-path. Equivalent to the "closepath" (Z and z) SVG command.

◆ cubic_bezier() [1/2]

virtual void Drawer::cubic_bezier	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		double	x,
		double	y
	)

pure virtual

Draws a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. All points in absolute coordinates. It is equivalent to the "C" SVG path instruction.

◆ cubic_bezier() [2/2]

virtual void Drawer::cubic_bezier	(	double	x2,
		double	y2,
		double	x,
		double	y
	)

pure virtual

Draws a cubic Bézier curve from the current point to (x,y). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an C, c, S or s, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). All points in absolute coordinates. It is equivalent to the "S" SVG path instruction.

◆ cubic_bezier_rel() [1/2]

virtual void Drawer::cubic_bezier_rel	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		double	x,
		double	y
	)

pure virtual

Draws a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. All points in absolute coordinates. It is equivalent to the "c" SVG path instruction.

◆ cubic_bezier_rel() [2/2]

virtual void Drawer::cubic_bezier_rel	(	double	x2,
		double	y2,
		double	x,
		double	y
	)

pure virtual

Draws a cubic Bézier curve from the current point to (x,y). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an C, c, S or s, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). All points in relative coordinates. It is equivalent to the "s" SVG path instruction.

◆ device_point_to_model()

virtual void Drawer::device_point_to_model	(	double *	x,
		double *	y
	)		const

pure virtual

Convert a point in device coordinates (e.g. pixels) to model coordinates (real world units, tenths of one millimeter).

◆ device_units_to_model()

virtual LUnits Drawer::device_units_to_model ( double value ) const

pure virtual

Convert device units (e.g. pixels) to model units (real world units, tenths of one millimeter).

◆ draw_bitmap()

virtual void Drawer::draw_bitmap	(	RenderingBuffer &	bmap,
		bool	hasAlpha,
		Pixels	srcX1,
		Pixels	srcY1,
		Pixels	srcX2,
		Pixels	srcY2,
		LUnits	dstX1,
		LUnits	dstY1,
		LUnits	dstX2,
		LUnits	dstY2,
		EResamplingQuality	resamplingMode,
		double	alpha = `1.0`
	)

pure virtual

Render part of a bitmap. It is somehow equivalent to the "image" SVG element.

Parameters

bmap	The struct RenderingBuffer containing the pointer to the bitmap and its dimensions in pixels.
hasAlpha	true when the bitmap has alpha channel information.
srcX1,srcY1,srcX2,srcY2	Top-left and bottom-right points of the source bitmap, in device units.
dstX1,dstY1,dstX2,dstY2	The destination top-left corner and bottom-right corner, in model units.
resamplingMode	Value from enum EResamplingQuality that defines how resampling (if required) must be done.
alpha	Transparency (alpha value: 1.0 opaque).

This method is currently used by Lomse when the Document includes a JPG or PNG image.

◆ draw_glyph()

virtual void Drawer::draw_glyph	(	double	x,
		double	y,
		unsigned int	ch
	)

pure virtual

Render a character. This method is equivalent to providing the x,y attributes for the "<text>" SVG element and the string content for that element.

Parameters

x,y	Destination point, in model coordinates (LUnits).
ch	The character to render.

◆ draw_glyph_rotated()

virtual void Drawer::draw_glyph_rotated	(	double	x,
		double	y,
		unsigned int	ch,
		double	rotation
	)

pure virtual

Render a character rotated. This method is equivalent to providing the x,y attributes for the "<text>" SVG element, the string content for that element and the rotation parameters for the affine transform.

Parameters

x,y	Destination point, in model coordinates (LUnits).
ch	The character to render.
rotation	The rotation to apply, in radians.

◆ draw_text() [1/2]

virtual int Drawer::draw_text	(	double	x,
		double	y,
		const std::string &	str
	)

pure virtual

Render text. This method is equivalent to providing the x,y attributes for the "<text>" SVG element and the string content for that element.

Parameters

x,y	Destination point, in model coordinates (LUnits).
str	The text to render.

◆ draw_text() [2/2]

virtual int Drawer::draw_text	(	double	x,
		double	y,
		const wstring &	str
	)

pure virtual

Render text. This method is equivalent to providing the x,y attributes for the "<text>" SVG element and the string content for that element.

Parameters

x,y	Destination point, in model coordinates (LUnits).
str	The text to render.

◆ end_composite_notation()

virtual void Drawer::end_composite_notation ( )

inlinevirtual

This method is used to inform the Drawer that the drawing of a composite element has finished.

◆ end_path()

virtual void Drawer::end_path ( )

pure virtual

Terminate a path. Equivalent to closing the SVG path element " />".

◆ fill()

virtual void Drawer::fill ( Color color )

pure virtual

Set the color to fill current open path. Color can have alpha value, if transparency is desired.

◆ fill_linear_gradient()

virtual void Drawer::fill_linear_gradient	(	LUnits	x1,
		LUnits	y1,
		LUnits	x2,
		LUnits	y2
	)

pure virtual

Set the currently defined linear gradient to be used for filling current open path. These methods are used by Lomse as follows:

//draw a rounded rectangle filled with a gradient color and a border
pDrawer->begin_path();
pDrawer->fill( normalColor );
pDrawer->stroke( strokeColor );
pDrawer->stroke_width(15.0);
Color white(255, 255, 255);
Color dark(40, 30, 20);
dark.a = 45;        //set alpha channel. It could have been included in color creation
Color light(dark);
light = light.gradient(white, 0.2);
pDrawer->gradient_color(white, 0.0, 0.1);
pDrawer->gradient_color(white, dark, 0.1, 0.7);
pDrawer->gradient_color(dark, light, 0.7, 1.0);
pDrawer->fill_linear_gradient(m_pos.x, m_pos.y,
                              m_pos.x, m_pos.y + m_height);
pDrawer->rect(pos, USize(width, height), 100.0f);
pDrawer->end_path();

◆ fill_none()

virtual void Drawer::fill_none ( )

pure virtual

Do not fill current open path.

◆ gradient_color() [1/2]

virtual void Drawer::gradient_color	(	Color	c1,
		Color	c2,
		double	start,
		double	stop
	)

pure virtual

Define a linear gradient that can be used in current open path.

◆ gradient_color() [2/2]

virtual void Drawer::gradient_color	(	Color	c1,
		double	start,
		double	stop
	)

pure virtual

Define a linear gradient that can be used in current open path.

◆ hline_to()

virtual void Drawer::hline_to ( double x )

pure virtual

Horizontal line to (absolute coordinates) command. It is equivalent to the "H" SVG path instruction.

◆ hline_to_rel()

virtual void Drawer::hline_to_rel ( double x )

pure virtual

Horizontal line to (relative coordinates) command. It is equivalent to the "h" SVG path instruction.

◆ is_ready()

virtual bool Drawer::is_ready ( ) const

pure virtual

Returns true if the Drawer is initialized and can be used.

◆ line()

virtual void Drawer::line	(	LUnits	x1,
		LUnits	y1,
		LUnits	x2,
		LUnits	y2,
		LUnits	width,
		ELineEdge	nEdge = `k_edge_normal`
	)

pure virtual

Draw a line segment that starts at one point and ends at another. It is equivalent to the "circle" SVG element.

◆ line_to()

virtual void Drawer::line_to	(	double	x,
		double	y
	)

pure virtual

Line to (absolute coordinates) command. It is equivalent to the abs. "lineto" (L) SVG path instruction.

◆ line_to_rel()

virtual void Drawer::line_to_rel	(	double	x,
		double	y
	)

pure virtual

Line to (relative coordinates) command. It is equivalent to the rel. "lineto" (l) SVG path instruction.

◆ line_with_markers()

virtual void Drawer::line_with_markers	(	UPoint	start,
		UPoint	end,
		LUnits	width,
		ELineCap	startCap,
		ELineCap	endCap
	)

pure virtual

SVG line with start/end markers. Absolute coordinates.

◆ model_point_to_device()

virtual void Drawer::model_point_to_device	(	double *	x,
		double *	y
	)		const

pure virtual

Convert a point in model coordinates (real world units, tenths of one millimeter) to device coordinates (e.g. pixels).

◆ model_to_device_units()

virtual double Drawer::model_to_device_units ( LUnits value ) const

pure virtual

Convert model units (real world units, tenths of one millimeter) to device units (e.g. pixels).

◆ move_to()

virtual void Drawer::move_to	(	double	x,
		double	y
	)

pure virtual

Move to (absolute coordinates) command. The effect is as if the "pen" were lifted and moved to a new location. It is equivalent to the abs. "moveto" (M) SVG path instruction.

◆ move_to_rel()

virtual void Drawer::move_to_rel	(	double	x,
		double	y
	)

pure virtual

Move to (relative coordinates) command. The effect is as if the "pen" were lifted and moved to a new location. It is equivalent to the rel. "moveto" (m) SVG path instruction.

◆ new_viewport_origin()

virtual void Drawer::new_viewport_origin	(	double	x,
		double	y
	)

virtual

Set a new origin for the viewport. Its size does not change. Received coordinates are in device units (e.g. Pixels).

◆ new_viewport_size()

virtual void Drawer::new_viewport_size	(	double	x,
		double	y
	)

virtual

Chage the size of the viewport. Its origin is not affected. Received values are in device units (e.g. Pixels).

◆ polygon()

virtual void Drawer::polygon	(	int	n,
		UPoint	points[]
	)

pure virtual

Draw a closed shape consisting of a set of connected straight line segments. It is equivalent to the "polygon" SVG element.

◆ quadratic_bezier() [1/2]

virtual void Drawer::quadratic_bezier	(	double	x1,
		double	y1,
		double	x,
		double	y
	)

pure virtual

Draws a quadratic Bézier curve from the current point to (x,y) using (x1,y1) as the control point. All points in absolute coordinates. It is equivalent to the "Q" SVG path instruction.

◆ quadratic_bezier() [2/2]

virtual void Drawer::quadratic_bezier	(	double	x,
		double	y
	)

pure virtual

Draws a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a Q, q, T or t, assume the control point is coincident with the current point.) All points in absolute coordinates. It is equivalent to the "T" SVG path instruction.

◆ quadratic_bezier_rel() [1/2]

virtual void Drawer::quadratic_bezier_rel	(	double	x1,
		double	y1,
		double	x,
		double	y
	)

pure virtual

Draws a quadratic Bézier curve from the current point to (x,y) using (x1,y1) as the control point. All points in relative coordinates. It is equivalent to the "q" SVG path instruction.

◆ quadratic_bezier_rel() [2/2]

virtual void Drawer::quadratic_bezier_rel	(	double	x,
		double	y
	)

pure virtual

Draws a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a Q, q, T or t, assume the control point is coincident with the current point.) All points in relative coordinates. It is equivalent to the "t" SVG path instruction.

◆ rect()

virtual void Drawer::rect	(	UPoint	pos,
		USize	size,
		LUnits	radius
	)

pure virtual

Draw a rectangle which is axis-aligned with the current user coordinate system. Rounded rectangles can be achieved by setting a non-zero value for the radius parameter. It is equivalent to the "rect" SVG element.

◆ remove_shift()

virtual void Drawer::remove_shift ( )

pure virtual

Remove the temporary shift defined in the set_shift() method.

◆ render()

virtual void Drawer::render ( )

pure virtual

Do render currently defined paths.

◆ reset()

virtual void Drawer::reset ( Color bgcolor )

pure virtual

Set the background color and prepare to render a new image.

◆ select_font()

virtual bool Drawer::select_font	(	const std::string &	language,
		const std::string &	fontFile,
		const std::string &	fontName,
		double	height,
		bool	fBold = `false`,
		bool	fItalic = `false`
	)

pure virtual

Select the font to be used form now on in all text rendering methods. The parameters are equivalent to the attibutes in the "text" SVG element.

Parameters

language	A language code drawn from ISO 639, optionally extended with a country code drawn from ISO 3166, as 'en-US'. It represents the default language for the texts to be rendered. If not specified "en" is assumed.
fontFile	Filename (without path) for the font file to use. This parameter is deprecated and should not be used; it will normally be empty.
fontName	The name of a font, as it is usually specified in the 'font-name' CCS property. But it must contain only one font name, without quotes, e.g.: "Times New Roman". It can be generic, e.g.: "sans".
height	Desired font height, in points.
fBold	true if the desired font weight is 'bold'.
fItalic	true if the desired font style is 'italic'.

The font file must be selected based on the values for all these parameters. If exact match is not possible it is expected than a substitution font be selected.

◆ set_affine_transformation()

virtual void Drawer::set_affine_transformation ( TransAffine & transform )

pure virtual

Set the affine transformation matrix to use.

◆ set_shift()

virtual void Drawer::set_shift	(	LUnits	x,
		LUnits	y
	)

pure virtual

Add a temporay shift to subsequent elements and paths created after invoking this method. It is a facility to avoid that classes using the drawer having to directly manipulate the affine matrix for some position adjustment.

◆ set_text_color()

virtual void Drawer::set_text_color ( Color color )

virtual

Define the font-color attribute to use from now on.

◆ start_composite_notation()

virtual void Drawer::start_composite_notation	(	std::string	UNUSEDid,
		std::string	UNUSEDclassname
	)

inlinevirtual

This method is used to inform the Drawer that the drawing of a new composite element (that is, an element requiring several SVG commands) is going to start.

◆ start_simple_notation()

virtual void Drawer::start_simple_notation	(	std::string	UNUSEDid,
		std::string	UNUSEDclassname
	)

inlinevirtual

This method is used to inform the Drawer that the drawing of a new simple element (that is, an element requiring just one SVG command) is going to start.

◆ stroke()

virtual void Drawer::stroke ( Color color )

pure virtual

Set the color to stroke current open path. Color can have alpha value, if transparency is desired.

◆ stroke_none()

virtual void Drawer::stroke_none ( )

pure virtual

Do not stroke current open path

◆ stroke_width()

virtual void Drawer::stroke_width ( double w )

pure virtual

Define the width (in model units, a tenth of one millimeter) of the line to stroke current open path.

◆ vline_to()

virtual void Drawer::vline_to ( double y )

pure virtual

Vertical line to (absolute coordinates) command. It is equivalent to the "V" SVG path instruction.

◆ vline_to_rel()

virtual void Drawer::vline_to_rel ( double y )

pure virtual

Vertical line to (relative coordinates) command. It is equivalent to the "v" SVG path instruction.

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ Drawer()

◆ ~Drawer()

Member Function Documentation

◆ accepts_id_class()

◆ add_path()

◆ begin_path()

◆ circle()

◆ close_path()

◆ cubic_bezier() [1/2]

◆ cubic_bezier() [2/2]

◆ cubic_bezier_rel() [1/2]

◆ cubic_bezier_rel() [2/2]

◆ device_point_to_model()

◆ device_units_to_model()

◆ draw_bitmap()

◆ draw_glyph()

◆ draw_glyph_rotated()

◆ draw_text() [1/2]

◆ draw_text() [2/2]

◆ end_composite_notation()

◆ end_path()

◆ fill()

◆ fill_linear_gradient()

◆ fill_none()

◆ gradient_color() [1/2]

◆ gradient_color() [2/2]

◆ hline_to()

◆ hline_to_rel()

◆ is_ready()

◆ line()

◆ line_to()

◆ line_to_rel()

◆ line_with_markers()

◆ model_point_to_device()

◆ model_to_device_units()

◆ move_to()

◆ move_to_rel()

◆ new_viewport_origin()

◆ new_viewport_size()

◆ polygon()

◆ quadratic_bezier() [1/2]

◆ quadratic_bezier() [2/2]

◆ quadratic_bezier_rel() [1/2]

◆ quadratic_bezier_rel() [2/2]

◆ rect()

◆ remove_shift()

◆ render()

◆ reset()

◆ select_font()

◆ set_affine_transformation()

◆ set_shift()

◆ set_text_color()

◆ start_composite_notation()

◆ start_simple_notation()

◆ stroke()

◆ stroke_none()

◆ stroke_width()

◆ vline_to()

◆ vline_to_rel()