This page has been translated automatically.
视频教程
界面
要领
高级
实用建议
专业(SIM)
UnigineEditor
界面概述
资源工作流程
版本控制
设置和首选项
项目开发
调整节点参数
Setting Up Materials
设置属性
照明
Sandworm
使用编辑器工具执行特定任务
如何擴展編輯器功能
嵌入式节点类型
Nodes
Objects
Effects
Decals
光源
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
编程
基本原理
搭建开发环境
使用范例
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
材质和着色器
Rebuilding the Engine Tools
GUI
双精度坐标
应用程序接口
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
创建内容
内容优化
材质
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

Unigine::WidgetCanvas Class

Header: #include <UnigineWidgets.h>
Inherits from: Widget

This class enables to create a canvas on which lines, polygons, and text can be drawn. It performs clipping of the visible region while rendering.

Notice
A polygon can be a triangle, a rectangle, a pentagon, and so on: it can have any number of sides. For example, if you add 4 points to the canvas via the addPolygonPoint() function, the 4 sided polygon will be drawn.

By default, all polygons are 2-sided, meaning that both sides of the polygon are visible at the same time. If it is necessary to make only one of them visible, you can set the 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
  • To reset the ID counter when re-drawing the widget canvas don't forget to call the clear() method.
  • The widget canvas doesn't perform depth testing. So, you will have to implement depth testing by using functions that set the rendering order for lines and polygons.

See Also#

  • A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder:
    • canvas_00
    • canvas_01
    • canvas_02
    • canvas_03
  • C++ API sample <UnigineSDK>/source/samples/Api/Widgets/WidgetCanvas
  • C# API sample <UnigineSDK>/source/csharp/samples/Api/Widgets/WidgetCanvas

WidgetCanvas Class

Members


static WidgetCanvasPtr create ( const Ptr<Gui> & gui ) #

Constructor. Creates a new canvas widget and adds it to the specified GUI.

Arguments

  • const Ptr<Gui> & gui - GUI, to which the canvas will belong.

static WidgetCanvasPtr create ( ) #

Constructor. Creates a new canvas widget and adds it to the Engine GUI.

void setColor ( const Math::vec4 & color ) #

Sets a background color for the canvas widget.

Arguments

  • const Math::vec4 & color - Background color.

Math::vec4 getColor ( ) const#

Returns the background color of the canvas widget.

Return value

Background color.

void setImage ( const Ptr<Image> & image ) #

Sets the image used as the default texture for new polygons added to the canvas widget.

Arguments

  • const Ptr<Image> & image - Texture image.

Ptr<Image> getImage ( ) const#

Returns the current default texture image used for new polygons added to the canvas widget.

Return value

Texture image.

int getLine ( int num ) const#

Returns the canvas element ID of the line by its number.

Arguments

  • int num - Line number in range from 0 to the total number lines.

Return value

Canvas element ID of the line.

void setLineColor ( int line, const Math::vec4 & color ) #

Updates the color of the specified line.

Arguments

  • int line - Canvas element ID of the line.
  • const Math::vec4 & color - Line color.

Math::vec4 getLineColor ( int line ) const#

Returns the current color of the specified line.

Arguments

  • int line - Canvas element ID of the line.

Return value

Line color.

int getLineIndex ( int line, int num ) const#

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 getLineIntersection ( int x, int y, float distance ) const#

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.

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.

int getLineOrder ( int line ) const#

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.

Math::vec3 getLinePoint ( int line, int num ) const#

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.

Return value

Segment point coordinates.

void setLineTransform ( int line, const Math::mat4 & transform ) #

Updates the transformation matrix of the specified line.

Arguments

  • int line - Canvas element ID of the line.
  • const Math::mat4 & transform - Transformation matrix.

Math::mat4 getLineTransform ( int line ) const#

Returns the current transformation matrix of the specified line.

Arguments

  • int line - Canvas element ID of the line.

Return value

Transformation matrix.

int getNumLineIndices ( int line ) const#

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 getNumLinePoints ( int line ) const#

Returns the number of the points that create line segments.

Arguments

  • int line - Canvas element ID of the line.

Return value

Number of line segment points.

int getNumLines ( ) const#

Returns the number of lines drawn in the canvas widget.

Return value

Number of lines.

int getNumPolygonIndices ( int polygon ) const#

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 polygons.

int getNumPolygonPoints ( int polygon ) const#

Returns the number of points that form the specified polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

Number of polygon points.

int getNumPolygons ( ) const#

Returns the number of polygons drawn in the canvas widget.

Return value

Number of polygons.

int getNumTexts ( ) const#

Returns the number of text strings drawn in the canvas widget.

Return value

Number of text strings.

int getPolygon ( int num ) const#

Returns the canvas element ID of the polygon by its index.

Arguments

  • int num - Polygon number in range from 0 to the total number of polygons.

Return value

Canvas element ID of the polygon.

int getPolygonBlendDestFunc ( int polygon ) const#

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 of the destination color (one of the BLEND_*).

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 BLEND_*).
  • int dest - Blending mode for the destination polygon color (one of the BLEND_*).

int getPolygonBlendSrcFunc ( int polygon ) const#

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 of the source screen buffer color (one of the BLEND_*).

void setPolygonColor ( int polygon, const Math::vec4 & color ) #

Updates the color of the specified polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const Math::vec4 & color - Polygon color.

Math::vec4 getPolygonColor ( int polygon ) const#

Returns the current color of the specified polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

Polygon color.

void setPolygonImage ( int polygon, const Ptr<Image> & image ) #

Sets an image for a given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const Ptr<Image> & image - Image to set.

Ptr<Image> getPolygonImage ( int polygon ) #

Returns the current image set for a given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

Current image set for the specified polygon.

int getPolygonIndex ( int polygon, int num ) const#

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.

int getPolygonIntersection ( int x, int y ) const#

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.

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.

int getPolygonOrder ( int polygon ) const#

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.

Math::vec3 getPolygonPoint ( int polygon, int num ) const#

Returns the coordinates of the specified polygon point.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • int num - Number of the polygon point.

Return value

Polygon point coordinates.

void setPolygonTexCoord ( int polygon, const Math::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.
  • const Math::vec2 & texcoord - Texture coordinates for the point.

Math::vec2 getPolygonTexCoord ( int polygon, int num ) const#

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.

Return value

Texture coordinates of the point.

void setPolygonTexture ( int polygon, const char * name ) #

Sets a texture from a file for the given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const char * name - Path to the texture.

const char * getPolygonTexture ( int polygon ) const#

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 setPolygonTransform ( int polygon, const Math::mat4 & transform ) #

Updates the transformation matrix of the specified polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const Math::mat4 & transform - Transformation matrix.

Math::mat4 getPolygonTransform ( int polygon ) const#

Returns the current transformation matrix of the specified polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

Transformation matrix.

void setPolygonTwoSided ( int polygon, int two_sided ) #

Sets polygon two sided option.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • int two_sided - two sided option.

int getPolygonTwoSided ( int polygon ) const#

Gets polygon two sided option.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

Returns two sided option.

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 getPolygonWrapRepeat ( int polygon ) const#

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 getText ( int num ) const#

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 setTextAlign ( int text, int align ) #

Updates the alignment of the specified text.

Arguments

  • int text - Canvas element ID of the text string.
  • int align - Text alignment. One or a combination of the Gui::ALIGN_* values (TOP, BOTTOM, LEFT, RIGHT, CENTER).

int getTextAlign ( int text ) const#

Returns the current alignment of the specified text.

Arguments

  • int text - Canvas element ID of the text string.

Return value

Text alignment. One or a combination of the Gui::ALIGN_* values (TOP, BOTTOM, LEFT, RIGHT, CENTER).

void setTextColor ( int text, const Math::vec4 & color ) #

Updates the color of the specified text.

Arguments

  • int text - Canvas element ID of the text string.
  • const Math::vec4 & color - Font color.

Math::vec4 getTextColor ( int text ) const#

Returns the current color of the specified text.

Arguments

  • int text - Canvas element ID of the text string.

Return value

Font color.

int getTextHeight ( int text ) const#

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.

int getTextIntersection ( int x, int y ) const#

Checks whether the specified point (e.g. the mouse cursor) intersects with a bounding box of widget text.

Arguments

  • int x - coordinate of the point.
  • int y - coordinate of the point.

Return value

ID of the intersected text lines array; otherwise, -1 is returned if no intersections are found.

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 getTextOrder ( int text ) const#

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 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. The default is 0 (no outlining).

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.

int getTextOutline ( int text ) const#

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.

void setTextPosition ( int text, const Math::vec2 & position ) #

Updates the position of the specified text.

Arguments

  • int text - Canvas element ID of the text string.
  • const Math::vec2 & position - Text position coordinates.

Math::vec2 getTextPosition ( int text ) const#

Returns the current position of the specified text.

Arguments

  • int text - Canvas element ID of the text string.

Return value

Text position coordinates.

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.

int getTextSize ( int text ) const#

Returns the current font size of the specified text.

Arguments

  • int text - Canvas element ID of the text string.

Return value

Font size.

void setTextText ( int text, const char * 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.
  • const char * str - Text string.

const char * getTextText ( int text ) const#

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.

void setTextTransform ( int text, const Math::mat4 & transform ) #

Updates the transformation matrix of the specified text.

Arguments

  • int text - Canvas element ID of the text string.
  • const Math::mat4 & transform - Transformation matrix.

Math::mat4 getTextTransform ( int text ) const#

Returns the current transformation matrix of the specified text.

Arguments

  • int text - Canvas element ID of the text string.

Return value

Transformation matrix.

void setTexture ( const char * texture ) #

Sets the texture that will be used by default for new polygons added to the canvas widget.

Arguments

  • const char * texture - Path to the texture.

const char * getTexture ( ) const#

Returns the path to the texture used by default for new polygons added to the canvas widget.

Return value

Path to the texture.

int getTextWidth ( int text ) const#

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 setTransform ( const Math::mat4 & transform ) #

Sets a transformation matrix applied to all primitives on the canvas widget.

Arguments

  • const Math::mat4 & transform - Transformation matrix.

Math::mat4 getTransform ( ) const#

Returns the transformation matrix applied to all primitives on the canvas widget.

Return value

Transformation matrix.

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.

int addLineIndex ( int line, int index ) #

Adds an index for the point of the line segment in the canvas widget. Notice that 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.

int addLinePoint ( int line, const Math::vec3 & point ) #

Adds a new segment to the line in the canvas widget.

Arguments

  • int line - Canvas element ID of the line.
  • const Math::vec3 & point - Segment point coordinates.

Return value

Number of the added line segment point.

int addLinePoint ( int line, const Math::vec2& point ) #

Adds a new segment to the line in the canvas widget.

Arguments

  • int line - Canvas element ID of the line.
  • const Math::vec2& point - Segment point coordinates.

Return value

Number of the added line segment point.

void setLinePoint ( int line, int num, const Math::vec3& point ) #

Sets a line segment in the canvas widget.

Arguments

  • int line - Canvas element ID of the line.
  • int num - Index of the point in the array of line points.
  • const Math::vec3& point - Line point coordinates.

void setLinePoint ( int line, int num, const Math::vec2& point ) #

Sets a line segment in the canvas widget.

Arguments

  • int line - Canvas element ID of the line.
  • int num - Index of the point in the array of line points.
  • const Math::vec2& point - Line point coordinates.

int addPolygon ( int polygon = 0 ) #

Adds a new polygon to the canvas widget. By default, it is rendered in white color. Texture tiling mode is disabled.

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.

int addPolygonIndex ( int polygon, int index ) #

Adds an index for the point of the polygon in the canvas widget. Notice that 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.

int addPolygonPoint ( int polygon, const Math::vec3 & point ) #

Adds a new point to the polygon in the canvas widget.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const Math::vec3 & point - Polygon point coordinates.

Return value

Number of the added polygon point.

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 (no outlining). 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.

void clear ( ) #

Clears the canvas widget: deletes all drawn lines, polygons and text.

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 clearLinePoints ( int line ) #

Deletes all points that make up a given line.

Arguments

  • int line - Canvas element ID of the line.

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 clearPolygonPoints ( int polygon ) #

Deletes all points that make up a given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

void removeLine ( int line ) #

Removes the line from the canvas widget.

Arguments

  • int line - Canvas element ID of the line.

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.

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 to remove.

void removePolygon ( int polygon ) #

Removes the polygon from the canvas widget.

Arguments

  • int polygon - Canvas element ID of the polygon.

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.

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 removeText ( int text ) #

Removes the text from the canvas widget.

Arguments

  • int text - Canvas element ID of the text string.

void setPolygonGPUTexture ( int polygon, const Ptr<Texture> & texture ) #

Sets a GPU texture for the given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.
  • const Ptr<Texture> & texture - GPU texture

Ptr<Texture> getPolygonGPUTexture ( int polygon ) const#

Returns the current GPU texture for the given polygon.

Arguments

  • int polygon - Canvas element ID of the polygon.

Return value

GPU texture

void setTextFont ( int text, const char * path ) #

Sets a new font to be used for the text with the given ID.

Arguments

  • int text - ID of the text.
  • const char * path - Path to the font file (.ttf) to be used.

void setTextPixelPerfect ( int text, bool pixel_perfect ) #

Sets the text with the given ID as pixel perfect.

Arguments

  • int text - ID of the text.
  • bool pixel_perfect - true to make the text pixel perfect, otherwise, false.

bool getTextPixelPerfect ( int text ) const#

Returns a value indicating if the text with the given ID is pixel perfect.

Arguments

  • int text - ID of the text.

Return value

true if the text is pixel perfect, otherwise, false.

void setPolygonIntersection ( int polygon, bool intersection ) #

Specifies whether the polygon with the given ID will participate in the intersection check.

Arguments

  • int polygon - ID of the polygon.
  • bool intersection - true to make the polygon participate in the intersection check, otherwise, false.

bool isPolygonIntersection ( int polygon ) const#

Returns a value indicating if the polygon with the given ID participates in the intersection check.

Arguments

  • int polygon - ID of the polygon.

Return value

true if the polygon participates in the intersection check, otherwise, false.

void setPolygonRender ( int polygon, bool render ) #

Sets the rendering state for the polygon with the given ID.

Arguments

  • int polygon - ID of the polygon.
  • bool render - true to render the polygon, otherwise, false.

bool isPolygonRender ( int polygon ) const#

Returns a value indicating if the polygon with the given ID is rendered.

Arguments

  • int polygon - ID of the polygon.

Return value

true if the polygon is rendered, otherwise, false.

int getPolygonTextureWidth ( int polygon ) const#

Returns the width of the polygon texture.

Arguments

  • int polygon - ID of the polygon.

Return value

Width of the polygon texture.

int getPolygonTextureHeight ( int polygon ) const#

Returns the height of the polygon texture.

Arguments

  • int polygon - ID of the polygon.

Return value

Height of the polygon texture.
Last update: 2023-10-11
Build: ()