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::WidgetSprite Class

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

This base class is used to create sprites, which are basically any widgets dealing with images.

A sprite has a background layer which is used to calculate a bounding box of the widget and in addition can have a number of layers. All layer including the bottom one can be assigned textures, tiled and blended.

Notice
You can transform all layers, but avoid rotating a background layer. Being used to calculate a bounding box, it stretches if rotated. Rotate layers instead.

See Also#

  • Widget Target Marker sample — an implementation of a HUD with a marker always pointing to the target in CPP Samples suite
  • TargetMarker sample — an implementation of a HUD with a marker always pointing to the target in C# Component Samples suite
  • A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder:
    • sprite_00
    • sprite_01
    • sprite_02
    • sprite_03
  • The Widgets article providing details on the sprite

WidgetSprite Class

Members


static WidgetSpritePtr create ( const Ptr<Gui> & gui, const char * name = 0 ) #

Constructor. Creates a sprite with a given texture and adds it to the specified GUI.

Arguments

  • const Ptr<Gui> & gui - GUI, to which the new sprite will belong.
  • const char * name - Path to the texture. This is an optional parameter.

static WidgetSpritePtr create ( const char * name = 0 ) #

Constructor. Creates a sprite with a given texture and adds it to the Engine GUI.

Arguments

  • const char * name - Path to the texture. This is an optional parameter.

int getBlendDestFunc ( ) const#

Returns the blending mode of the destination widget colour set for the first (bottom) layer of the sprite.

Return value

Blending mode (one of the BLEND_* variables).

void setBlendFunc ( int src, int dest ) #

Sets blending coefficients for the first (bottom) layer of the sprite. This layer always exists in the sprite.

Arguments

  • int src - Blending mode for the source screen buffer color (one of the BLEND_* variables).
  • int dest - Blending mode for the destination widget color (one of the BLEND_* variables).

int getBlendSrcFunc ( ) const#

Returns the blending mode of the source screen buffer colour set for the first (bottom) layer of the sprite.

Return value

Blending mode (one of the BLEND_* variables).

void setBufferMask ( int mask ) #

Sets a channel mask for the whole sprite. If a mask for a channel exists, one can draw in this channel. The default is BUFFER_ALL.

Arguments

  • int mask - Current channel mask (one of the BUFFER_* pre-defined variables).

int getBufferMask ( ) const#

Returns the current channel mask for the whole sprite.

Return value

Current channel mask (one of the BUFFER_* pre-defined variables).

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

Sets a color for the first (bottom) layer of the sprite. This layer always exists in the sprite.

Arguments

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

Math::vec4 getColor ( ) const#

Returns the current color set for the first (bottom) layer of the sprite.

Return value

Modulation color.

void setImage ( const Ptr<Image> & image, int dynamic = 0 ) #

Sets a loaded into memory image for the first (bottom) layer of the sprite. This layer always exists in the sprite. An additional flag can be set in case the sprite image is going to be updated often or even each frame (for optimized memory management).
Warning
Not available for the WidgetSpriteViewport !

Arguments

  • const Ptr<Image> & image - Pointer to the image.
  • int dynamic - Positive number if the image will be updated each frame; otherwise, 0.

Ptr<Image> getImage ( ) const#

Returns the loaded into memory image that is currently set for the first (bottom) layer of the sprite.
Warning
Not available for the WidgetSpriteViewport !

Return value

Pointer to the image.

int getLayerBlendDestFunc ( int layer ) const#

Returns the blending mode of the destination widget colour set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Blending mode (one of the BLEND_* variables).

void setLayerBlendFunc ( int layer, int src, int dest ) #

Sets blending coefficients for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • int src - Blending mode for the source color (one of the BLEND_* variables).
  • int dest - Blending mode for the destination color (one of the BLEND_* variables).

int getLayerBlendSrcFunc ( int layer ) const#

Returns the blending mode of the source screen buffer colour set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Blending mode (one of the BLEND_* variables).

void setLayerBufferMask ( int layer, int mask ) #

Sets a channel mask for a given layer of the sprite. If a mask for a channel exists, one can draw in this channel. The default is BUFFER_ALL.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • int mask - Channel mask. One of the BUFFER_* pre-defined variables.

int getLayerBufferMask ( int layer ) const#

Returns the current channel mask set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Channel mask. One of the BUFFER_* pre-defined variables.

void setLayerColor ( int layer, const Math::vec4 & color ) #

Sets a color for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const Math::vec4 & color - Modulation color.

Math::vec4 getLayerColor ( int layer ) const#

Returns the current color set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers..

Return value

Modulation color.

void setLayerEnabled ( int layer, bool enabled ) #

Sets a value indicating if the layer is enabled for rendering.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • bool enabled - 1 to enable the layer; 0 to disable it.

int isLayerEnabled ( int layer ) const#

Returns a value indicating if the layer is enabled for rendering.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Returns 1 if the layer is enabled; 0 if disabled.

int getLayerHeight ( int layer ) const#

Returns the current width of the layer (regardless of layer transformation).

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Width of the layer in units.

void setLayerImage ( int layer, const Ptr<Image> & image, int dynamic = 0 ) #

Sets an image for a given layer of the sprite. An additional flag can be set in case the sprite image is going to be updated often or even each frame (for optimized memory management).

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const Ptr<Image> & image - Image to set.
  • int dynamic - Positive number if the image will be updated each frame; otherwise, 0.

Ptr<Image> getLayerImage ( int layer ) const#

Returns the current image set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Current image set for the specified sprite layer.

void setLayerRender ( int layer, const Ptr<Texture> & texture, int flipped = 0 ) #

Sets a texture for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const Ptr<Texture> & texture - Pointer to the texture.
  • int flipped - Flipped flag.

Ptr<Texture> getLayerRender ( int layer ) const#

Returns the current texture set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Pointer to the texture.

void setLayerTexCoord ( int layer, const Math::vec4 & texcoord ) #

Sets the coordinates of the texture for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const Math::vec4 & texcoord - Texture coordinates. The first pair of coordinates (x and y) is for the upper left corner, the second pair (z and w) is for the lower right corner.

Math::vec4 getLayerTexCoord ( int layer ) const#

Returns the current coordinates of the texture set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Texture coordinates. The first pair of coordinates (x and y) is for the upper left corner, the second pair (z and w) is for the lower right corner.

void setLayerTexture ( int layer, const char * name ) #

Sets a texture for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const char * name - Path to the texture.

const char * getLayerTexture ( int layer ) const#

Returns the current texture set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Path to the texture.

void setLayerTransform ( int layer, const Math::mat4 & transform ) #

Sets a transformation matrix for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • const Math::mat4 & transform - Transformation matrix.

Math::mat4 getLayerTransform ( int layer ) const#

Returns the current transformation matrix set for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Transformation matrix.

int getLayerWidth ( int layer ) const#

Returns the current width of the layer (regardless of layer transformation).

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

Width of the layer in units.

void setLayerWrapRepeat ( int layer, int repeat ) #

Sets texture tiling for a given layer of the sprite.
Notice
To see tiling in effect, you need to transform sprite texture coordinates via setLayerTexCoord().

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.
  • int repeat - Positive number to enable texture tiling; 0 to disable it.

int getLayerWrapRepeat ( int layer ) const#

Returns a value indicating if texture tiling is enabled for a given layer of the sprite.

Arguments

  • int layer - Layer number in range from 0 to the total number of sprite layers.

Return value

true if texture tiling is enabled; false if disabled.

int getNumLayers ( ) const#

Returns the total number of layers in the sprite.

Return value

Number of layers.

void setRender ( const Ptr<Texture> & texture, int flipped = 0 ) #

Sets a texture to be rendered for the first (bottom) layer of the sprite.
Warning
Not available for the WidgetSpriteViewport !

Arguments

  • const Ptr<Texture> & texture - Pointer to the texture.
  • int flipped - Flipped flag.

Ptr<Texture> getRender ( ) const#

Returns the pointer to the texture that is currently set for the first (bottom) layer of the sprite.
Warning
Not available for the WidgetSpriteViewport !

Return value

Pointer to the texture.

void setTexCoord ( const Math::vec4 & coord ) #

Sets the coordinates of the texture for the first (bottom) layer of the sprite. This layer always exists in the sprite.

Arguments

  • const Math::vec4 & coord - Texture coordinates. The first pair of coordinates (x and y) is for the upper left corner, the second pair (z and w) is for the lower right corner.

Math::vec4 getTexCoord ( ) const#

Returns the current coordinates of the texture set for the first (bottom) layer of the sprite.

Return value

Texture coordinates. The first pair of coordinates (x and y) is for the upper left corner, the second pair (z and w) is for the lower right corner.

void setTexture ( const char * texture ) #

Sets a texture from a file for the first (bottom) layer of the sprite. This layer always exists in the sprite.

Arguments

  • const char * texture - Path to the texture.

const char * getTexture ( ) const#

Returns the texture from a file that is currently set for the first (bottom) layer of the sprite.

Return value

Path to the texture.

void setTransform ( const Math::mat4 & transform ) #

Sets a transformation matrix for the first (bottom) layer of the sprite. This layer always exists in the sprite.

Arguments

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

Math::mat4 getTransform ( ) const#

Returns the current transformation matrix set for the first (bottom) layer of the sprite.

Return value

Transformation matrix.

void setWrapRepeat ( int repeat ) #

Sets texture tiling for the first (bottom) layer of the sprite. This layer always exists in the sprite. The default is 0 (no tiling). To see tiling in effect, you need to transform sprite texture coordinates via setTexCoord().

Arguments

  • int repeat - 1 to enable texture tiling; 0 to disable it.

int getWrapRepeat ( ) const#

Returns a value indicating if texture tiling is enabled for the first (bottom) layer of the sprite.

Return value

Returns 1 if texture tiling is enabled; 0 if disabled.

int addLayer ( ) #

Adds an empty layer with default properties to the sprite.

Return value

Number of the added layer.

void removeLayer ( int layer ) #

Removes a given layer from the sprite.

Arguments

  • int layer - Layer number in range from 1 to the total number of sprite layers.

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

Sets the specified image as a mask for defining intersections with the mouse.
Notice
The image is converted to the R8 format.

Arguments

  • const Ptr<Image> & image - Image to be used as a mask for defining intersections.

void setIntersectionImageName ( const char * name ) #

Sets the specified image as a mask for defining intersections with the mouse.
Notice
The image is converted to the R8 format.

Arguments

  • const char * name - Name of the image to be used as a mask for defining intersections.

Ptr<Image> getIntersectionImage ( ) const#

Returns the image used as a mask for defining intersections with the mouse.
Notice
The image is converted to the R8 format.

Return value

Image to be used as a mask for defining intersections.

void setIntersectionImageTransform ( const Math::mat4 & transform ) #

Sets the transformation for the image used as a mask for defining intersections with the mouse.

Arguments

  • const Math::mat4 & transform - Image transformation.

Math::mat4 getIntersectionImageTransform ( ) const#

Returns the transformation for the image used as a mask for defining intersections with the mouse.

Return value

Image transformation.

void setIntersectionImageThreshold ( float threshold ) #

Sets the threshold value for the pixel. If the pixel value in the intersection mask is higher that the threshold, the intersection is detected.

Arguments

  • float threshold - Threshold value for the pixel.

float getIntersectionImageThreshold ( ) const#

Sets the threshold value for the pixel. If the pixel value in the intersection mask is higher that the threshold, the intersection is detected.

Return value

Threshold value for the pixel.

void setIntersectionImageEnabled ( bool enabled = false ) #

Sets the flag defining if the intersection image is used as a mask for detecting intersections with the mouse.

Arguments

  • bool enabled - true to enable the intersection image; false to disable it.

bool isIntersectionImageEnabled ( ) const#

Returns the value showing if the intersection image is used as a mask for detecting intersections with the mouse.

Return value

true if the intersection image is enabled; otherwise false.
Last update: 2023-07-06
Build: ()