WidgetCanvas Class
This class enables to create a canvas on which lines, polygons and a text can be drawn. It performs clipping of the visible region while rendering.
Notice
A polygon can be not only a triangle but also a rectangle, pentagon and so on: it can have any number of sides. For example, if you add 4 points to the canvas by using the addPolygonPoint() function,
the 4 sided polygon will be drawn.
By default, all polygons are 2-sided. It means that both sides of the polygon are visible at a time. If it is necessary to make visible only 1 side of the polygon, you can set a 2-sided flag to 0.
To increase performance, you can use point indices instead of point coordinates. See the following functions for more details:
Notice
The widget canvas doesn't perform a depth test. So, you will have to implement depth testing by using functions that set the rendering order
for lines and polygons.
WidgetCanvas Class
Members
WidgetCanvas (Gui gui)
Constructor. Creates a new canvas widget.Arguments
- Gui gui - GUI, to which the canvas will belong.
int getPolygonOrder (int polygon)
Returns the rendering order of the given polygon (the higher the value, the later the polygon is rendered atop other elements).Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Rendering order.void setLineOrder (int line, int order)
Updates the rendering order of the given line (the higher the value, the later the line will be rendered atop other elements).Arguments
- int line - Canvas element ID of the line.
- int order - Rendering order.
WidgetCanvas create (Widget widget)
WidgetCanvas constructor.Arguments
- Widget widget - Widget smart pointer.
Return value
int addPolygon (int polygon = 0)
Adds a new polygon to the canvas widget. By default, it is rendered in white color. The blending mode for:- The source screen buffer color is GUI_BLEND_SRC_ALPHA.
- The destination polygon color is GUI_BLEND_ONE_MINUS_SRC_ALPHA.
Arguments
- int polygon - Rendering order (the higher the value, the later the polygon will be rendered atop other elements).
Return value
Canvas element ID for the added polygon.void setPolygonTransform (int polygon, mat4 transform)
Updates the transformation matrix of the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- mat4 transform - Transformation matrix.
int addPolygonPoint (int polygon, vec3 point)
Adds a new point to the polygon in the canvas widget.Arguments
- int polygon - Canvas element ID of the polygon.
- vec3 point - Polygon point coordinates.
Return value
The number of the added polygon point in the array of polygon points.int getNumLinePoints (int line)
Returns the number of the points that form line segments.Arguments
- int line - Canvas element ID of the line.
Return value
The number of line segment points.mat4 getTransform ()
Returns a transformation matrix applied to all primitives on the canvas widget.Return value
Transformation matrix.void removePolygonPoint (int polygon, int num)
Removes the point of the polygon from the canvas widget.Arguments
- int polygon - Canvas element ID of the polygon.
- int num - Polygon point coordinates.
void removeLineIndex (int line, int num)
Removes the index with the given number from the array of the line indices.Arguments
- int line - Canvas element ID of the line.
- int num - The number of the index in the array of the line indices.
int getNumLineIndices (int line)
Returns the total number of indices set for the points that form line segments.Arguments
- int line - Canvas element ID of the line.
Return value
The number of indices set for the points that form line segments.int getTextIntersection (int x, int y)
Checks whether the specified point (e.g. the mouse cursor) intersects with a bounding box of widget text.Arguments
- int x - X coordinate of the point.
- int y - Y coordinate of the point.
Return value
ID of intersected text lines array; otherwise, -1 is returned if no intersections are found.vec4 getPolygonColor (int polygon)
Returns the current color of the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Polygon color.void setTextPosition (int text, vec2 position)
Updates the position of the specified text.Arguments
- int text - Canvas element ID of the text string.
- vec2 position - Text position.
vec4 getColor ()
Returns the background color for the widget.Return value
Background color.void setColor (vec4 color)
Sets the background color for the widget.Arguments
- vec4 color - Background color.
void setTextOutline (int text, int outline)
Sets a value indicating if the text should be rendered casting a shadow. Positive or negative values set the distance in pixels to offset the outline.Arguments
- int text - Canvas element ID of the text string.
- int outline - Outline offset:
- Positive values set offset in the bottom-right corner direction.
- Negative values set offset in the top-left corner direction (the outline will overlap widget text).
- 0 is not to use outlining.
void setPolygonTexCoord (int polygon, vec2 texcoord)
Updates the texture coordinates for the last added point of the polygon. Before calling this function, the point should be added with addPolygonPoint().Arguments
- int polygon - Canvas element ID of the polygon.
- vec2 texcoord - Texture coordinates for the point.
vec4 getLineColor (int line)
Returns the current color of the specified line.Arguments
- int line - Canvas element ID of the line.
Return value
Line color.void clearLineIndices (int line)
Clears the array of indices set for points that form the given line.Arguments
- int line - Canvas element ID of the line.
void setImage (Image image)
Updates the texture image for the canvas widget.Arguments
- Image image - Texture image.
void setTransform (mat4 transform)
Sets a transformation matrix applied to all primitives on the canvas widget.Arguments
- mat4 transform - Transformation matrix.
void removeLine (int line)
Removes the line from the canvas widget.Arguments
- int line - Canvas element ID of the line.
int getTextOutline (int text)
Returns a value indicating if the text is rendered casting a shadow. Positive or negative values determine the distance in pixels used to offset the outline.Arguments
- int text - Canvas element ID of the text string.
Return value
Positive value if the outline is offset in the bottom-right corner direction. Negative value if the outline is offset in the top-left corner direction. 0 if font is not outlined.vec4 getTextColor (int text)
Returns the current color of the specified text.Arguments
- int text - Canvas element ID of the text string.
Return value
Font color.vec2 getTextPosition (int text)
Returns the current position of the specified text.Arguments
- int text - Canvas element ID of the text string.
Return value
Text position.int getLine (int num)
Returns the canvas element ID of the line by its number.Arguments
- int num - Number of the line in the array of lines drawn in the widget canvas.
Return value
Canvas element ID of the line.void setLineTransform (int line, mat4 transform)
Updates the transformation matrix of the specified line.Arguments
- int line - Canvas element ID of the line.
- mat4 transform - Transformation matrix.
void setTextTransform (int text, mat4 transform)
Updates the transformation matrix of the specified text.Arguments
- int text - Canvas element ID of the text string.
- mat4 transform - Transformation matrix.
void setTextOrder (int text, int order)
Updates the rendering order of the given text element (the higher the value, the later the text will be rendered atop other elements).Arguments
- int text - Canvas element ID of the text string.
- int order - Rendering order.
int getText (int num)
Returns the canvas element ID of the text string by its number.Arguments
- int num - Number of the text element.
Return value
Canvas element ID of the text string.void setPolygonTwoSided (int polygon, int two_sided)
Updates the 2-sided flag for the given polygon. This flag is used when it is necessary to make visible only 1 side of the polygon. If the 2-sided flag is set to 0, only 1 side of the polygon is visible at a time on the canvas widget.Notice
By default, all polygons are 2-sided.
Arguments
- int polygon - Canvas element ID of the polygon.
- int two_sided - 1 to make the polygon 2-sided; otherwise, 0.
void setTexture (string texture)
Updates the name of the texture for the canvas widget.Arguments
- string texture - Texture name.
int getNumPolygonIndices (int polygon)
Returns the total number of indices set for points of the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
The number of indices set for points that form the polygon.void clearPolygonPoints (int polygon)
Clears the array of points that form the given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
int getPolygonIntersection (int x, int y)
Checks whether the specified point (e.g. the mouse cursor) intersects with widget polygons.Arguments
- int x - X coordinate of the point.
- int y - Y coordinate of the point.
Return value
Number of the first intersected polygon with the highest rendering order in the array of polygons. If no intersections are found, -1 will be returned.int type ()
WidgetWindow type.Return value
WidgetWindow type identifier.int getPolygon (int num)
Returns the canvas element ID of the polygon by its number.Arguments
- int num - Number of the polygon in the array of polygons drawn in the widget canvas.
Return value
Canvas element ID of the polygon.int getTextWidth (int text)
Returns the width of the given text element on the canvas widget.Arguments
- int text - Canvas element ID of the text string.
Return value
Text width in pixels.void setPolygonOrder (int polygon, int order)
Updates the rendering order of the given polygon (the higher the value, the later the polygon will be rendered atop other elements).Arguments
- int polygon - Canvas element ID of the polygon.
- int order - Rendering order.
void setLineColor (int line, vec4 color)
Updates the color of the specified line.Arguments
- int line - Canvas element ID of the line.
- vec4 color - Line color.
int addText (int order = 0)
Adds a new text string to the canvas widget. By default, it is rendered in white color. If a font size is not set for the canvas widget, a default one is used. No shadow is cast from a text. Text width and height on the canvas widget are equal to 0.Arguments
- int order - Rendering order (the higher the value, the later the text will be rendered atop other elements).
Return value
Canvas element ID of the added text string.int getLineOrder (int line)
Returns the rendering order of the given line (the higher the value, the later the line is rendered atop other elements).Arguments
- int line - Canvas element ID of the line.
Return value
Rendering order.void setPolygonTexture (int polygon, string name)
Sets a texture from a file for the given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- string name - Path to the texture.
void setPolygonWrapRepeat (int polygon, int repeat)
Sets texture tiling for a given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- int repeat - Positive number to enable texture tiling; 0 to disable it.
int addLinePoint (int line, vec3 point)
Adds a new segment to the line in the canvas widget.Arguments
- int line - Canvas element ID of the line.
- vec3 point - Segment point coordinates.
Return value
The number of the added line segment point in the array of line points.int getPolygonTwoSided (int polygon)
Returns the value of the 2-sided flag set for the given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
1 if the polygon is 2-sided; otherwise, 0.int getPolygonBlendDestFunc (int polygon)
Returns the blending mode of the destination color for the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Blending mode (one of the GUI_BLEND_* variables):- GUI_BLEND_NONE = 0
- GUI_BLEND_ZERO
- GUI_BLEND_ONE
- GUI_BLEND_SRC_COLOR
- GUI_BLEND_ONE_MINUS_SRC_COLOR
- GUI_BLEND_SRC_ALPHA
- GUI_BLEND_ONE_MINUS_SRC_ALPHA
- GUI_BLEND_DEST_COLOR
- GUI_BLEND_ONE_MINUS_DEST_COLOR
- GUI_BLEND_DEST_ALPHA
- GUI_BLEND_ONE_MINUS_DEST_ALPHA
void removeText (int text)
Removes the text from the canvas widget.Arguments
- int text - Canvas element ID of the text string.
mat4 getTextTransform (int text)
Returns the current transformation matrix of the specified text.Arguments
- int text - Canvas element ID of the text string.
Return value
Transformation matrix.void removeLinePoint (int line, int num)
Removes the segment of the line from the canvas widget.Arguments
- int line - Canvas element ID of the line.
- int num - Number of the point in the array of the line points.
void setPolygonImage (int polygon, Image image)
Sets an image for a given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- Image image - Image to set.
string getPolygonTexture (int polygon)
Returns the current texture set for a given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Path to the texture.void getImage (Image image)
Returns the current texture image set for the canvas widget.Arguments
- Image image
mat4 getLineTransform (int line)
Returns the current transformation matrix of the specified line.Arguments
- int line - Canvas element ID of the line.
Return value
Transformation matrix.int getNumPolygonPoints (int polygon)
Returns the number of points that form the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
The number of polygon points.int addLine (int order = 0)
Adds a new line to the canvas widget. By default, it is rendered in white color.Arguments
- int order - Rendering order (the higher the value, the later the line will be rendered atop other elements).
Return value
Canvas element ID for the added line.vec3 getLinePoint (int line, int num)
Returns the coordinates of the specified line segment point.Arguments
- int line - Canvas element ID of the line.
- int num - Number of the line segment point in the array of line points.
Return value
Segment point coordinates.int getLineIntersection (int x, int y, float distance)
Checks whether the specified point (e.g. the mouse cursor) intersects with lines drawn in the canvas widget.Arguments
- int x - X coordinate of the point.
- int y - Y coordinate of the point.
- float distance - Point radius acceptable for detecting intersection.
Return value
Number of the first intersected line with the highest rendering order in the array of lines. If no intersections are found, -1 will be returned.vec2 getPolygonTexCoord (int polygon, int num)
Returns the texture coordinates of the specified point of the polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- int num - Number of the polygon point in the array of polygon points.
Return value
Texture coordinates of the point.int addPolygonIndex (int polygon, int index)
Adds an index for the point of the polygon in the canvas widget.Notice
Before adding indices, you should add all points that form the polygon.
Arguments
- int polygon - Canvas element ID of the polygon.
- int index - Index of the point of the polygon.
Return value
The number of the added index in the array of polygon indices.void setTextSize (int text, int size)
Updates the font size of the specified text.Arguments
- int text - Canvas element ID of the text string.
- int size - Font size.
void clearPolygonIndices (int polygon)
Clears the array of indices set for points that form the given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
void setPolygonColor (int polygon, vec4 color)
Updates the color of the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- vec4 color - Polygon color.
int getPolygonBlendSrcFunc (int polygon)
Returns the blending mode of the source screen buffer color for the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Blending mode (one of the GUI_BLEND_* variables):- GUI_BLEND_NONE = 0
- GUI_BLEND_ZERO
- GUI_BLEND_ONE
- GUI_BLEND_SRC_COLOR
- GUI_BLEND_ONE_MINUS_SRC_COLOR
- GUI_BLEND_SRC_ALPHA
- GUI_BLEND_ONE_MINUS_SRC_ALPHA
- GUI_BLEND_DEST_COLOR
- GUI_BLEND_ONE_MINUS_DEST_COLOR
- GUI_BLEND_DEST_ALPHA
- GUI_BLEND_ONE_MINUS_DEST_ALPHA
int getLineIndex (int line, int num)
Returns the index of the point of the line segment by its number.Arguments
- int line - Canvas element ID of the line.
- int num - The number of the index of the point of the line segment.
Return value
Index of the point of the line segment.int getTextSize (int text)
Returns the current font size of the specified text.Arguments
- int text - Canvas element ID of the text string.
Return value
Font size.int getTextOrder (int text)
Returns the rendering order of the given text element (the higher the value, the later the text is rendered atop other elements).Arguments
- int text - Canvas element ID of the text string.
Return value
Rendering order.void clearLinePoints (int line)
Clears the array of points that form the given line.Arguments
- int line - Canvas element ID of the line.
vec3 getPolygonPoint (int polygon, int num)
Returns the coordinates of the specified polygon point.Arguments
- int polygon - Canvas element ID of the polygon.
- int num - Number of the polygon point in the array of polygon points.
Return value
Polygon point coordinates.int getNumPolygons ()
Returns the number of polygons drawn in the canvas widget.Return value
The number of polygons.int getTextHeight (int text)
Returns the height of the given text element on the canvas widget.Arguments
- int text - Canvas element ID of the text string.
Return value
Text height in pixels.void removePolygon (int polygon)
Removes the polygon from the canvas widget.Arguments
- int polygon - Canvas element ID of the polygon.
void clear ()
Clears the canvas widget: deletes all drawn lines, polygons and text.int getPolygonIndex (int polygon, int num)
Returns the index of the point of the polygon by its number.Arguments
- int polygon - Canvas element ID of the polygon.
- int num - The number of the index of the point of the polygon.
Return value
Index of the point of the polygon.void setPolygonBlendFunc (int polygon, int src, int dest)
Updates the blending coefficients for specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- int src - Blending mode for the source screen buffer color (one of the GUI_BLEND_* variables).
- int dest - Blending mode for the destination polygon color (one of the GUI_BLEND_* variables).
int addLineIndex (int line, int index)
Adds an index for the point of the line segment in the canvas widget.Notice
Before adding indices, you should add all points that form the line.
Arguments
- int line - Canvas element ID of the line.
- int index - Index of the point of the line segment.
Return value
The number of the added index in the array of line indices.void setTextText (int text, string str)
Updates the text to be drawn in the given text element on the canvas widget.Arguments
- int text - Canvas element ID of the text string.
- string str - Text string.
void removePolygonIndex (int polygon, int num)
Removes the index with the given number from the array of the polygon indices.Arguments
- int polygon - Canvas element ID of the polygon.
- int num - The number of the index in the array of the polygon indices.
int getNumLines ()
Returns the number of lines drawn in the canvas widget.Return value
The number of lines.int getPolygonWrapRepeat (int polygon)
Returns a value indicating if texture tiling is enabled for the given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
1 if texture tiling is enabled; 0 if disabled.int getNumTexts ()
Returns the number of text strings drawn in the canvas widget.Return value
The number of text strings.void getPolygonImage (int polygon, Image image)
Returns the current image set for a given polygon.Arguments
- int polygon - Canvas element ID of the polygon.
- Image image - Current image.
void setTextColor (int text, vec4 color)
Updates the color of the specified text.Arguments
- int text - Canvas element ID of the text string.
- vec4 color - Font color.
mat4 getPolygonTransform (int polygon)
Returns the current transformation matrix of the specified polygon.Arguments
- int polygon - Canvas element ID of the polygon.
Return value
Transformation matrix.string getTextText (int text)
Returns the current text drawn in the given text element on the canvas widget.Arguments
- int text - Canvas element ID of the text string.
Return value
Text string.string getTexture ()
Returns the name of the current texture set for the canvas widget.Return value
Texture name.Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)