Gui - stingray.Gui object reference - Stingray Lua API Reference
Description
A Gui is an object that manages primitive 2D shapes -- like rectangles, triangles, and text -- and draws them in the engine viewport.
Gui types
Each Gui has an origin, and an internal coordinate system. You set these up when you create the Gui object:
Use World.create_screen_gui() to create a Gui whose origin is fixed at the bottom left corner of the viewport. This kind of Gui always measures coordinates in pixels of screen space. Shapes that you draw in a screen Gui are always overlaid on top of the objects in the scene, never occluded by objects in the scene.
This kind of Gui is typically used for UI elements that need to remain always visible. Often, these elements tend to be fixed with respect to the viewport dimensions. For example, HUDs, menus, or targeting reticules.
Use World.create_world_gui() to create a Gui whose origin is located at a specified transform matrix in the 3D world. Its coordinates are typically measured in world units (meters). Shapes drawn by world space Guis are placed into the scene, so they are occluded by other surfaces that are interposed between the camera and the shape.
This kind of Gui is typically used for UI elements that need to be placed with respect to something in the scene, like information about specific objects or characters, markers that point to goal points in a map, or debug rendering of positions and volumes in the 3D world.
Shapes and drawing planes
Most shapes that you add to a Gui are 2D shapes, drawn on a 2D plane. By default, that plane is equivalent to the (x,z) plane of the Gui at its origin.
Shapes are located within their drawing plane by the position of their lower-left corner. When you create a shape, you can also provide a local position offset for the lower-left corner of the shape. This offset moves the shape away from the origin, while keeping it on the drawing plane.
The X coordinate of this position offset moves the shape to the right on the drawing plane. When you're using a screen-space Gui, the effect of increasing this X coordinate value is to move the shape to the right on the screen. When you're using a world-space Gui, the effect is to move the shape along the Gui's local X axis.
The Y coordinate of this position moves the shape up on the drawing plane. When you're using a screen-space Gui, the effect of increasing this Y coordinate value is to move the shape up on the screen. When you're using a world-space Gui, the effect is to move the shape along the Gui's local Z axis.
The Z coordinate for this position is interpreted differently, depending on whether you use a 2D or _3d function to create your shape. See the sections below.
2D functions
When you use a function like bitmap(), rect(), text(), or video() to add a shape to a Gui, the shape's drawing plane is always located at the Gui's origin.
If you provide a position offset for your shape on this plane, the Z coordinate of the offset sets the draw layer for the shape (see "Draw layers" below).
If you want to use the default draw layer of 0, you can provide the offset as a Vector2, without a Z coordinate.
_3d functions
When you use a function like bitmap_3d(), rect_3d(), text_3d(), or video_3d() to add a shape to a Gui, you can give your shape its own transform matrix within the Gui's 3D coordinate system. This matrix locates the origin of your shape's drawing plane.
Note that when you set this matrix, you'll be using 3D coordinates within the Gui's 3D space, not the (x,y) coordinates that you use for position offsets. That means that the Z axis for this matrix will be up.
Your shape's drawing plane will be along the (x,z) plane of this transform matrix. The position offset that you provide for your shape sets the shape's X and Y offsets on that drawing plane, as for plain 2D shapes. The Z coordinate of the position offset sets the depth of the 2D shape with respect to that drawing plane. Increasing the Z coordinate value moves the shape back into the drawing plane, decreasing the value below 0 moves the shape forward out of of the drawing plane.
If you use these _3d functions with a screen-space Gui, the effect is to rotate and/or skew the shape. Since the origin of the Gui is fixed to the viewport, you can only look at the shape from one direction: straight in to the Gui's drawing plane. Therefore, when you transform the shape in the Gui's 3D space, the effect of your transformation is effectively flattened or re-projected into the 2D screen space.
If you use these functions with a world-space Gui, you can make your 2D shapes appear anywhere in the 3D world. A common way to set this up is to initially create a world-space Gui with the Matrix4x4.identity() matrix, and with a width and height ratio to world space units of 1. Then, when you want to draw a shape in the 3D world, you create the shape with a transform matrix that locates the lower-left corner of the shape at the world-space position and rotation that you want it to appear. In this scenario, you can leave the position offset at (0,0,0).
triangle function
The exception to the 2D and 3D usage rules above is the triangle() function. Unlike the _3d functions above, the positions you specify for the triangle do not locate a drawing plane for a 2D shape. Instead, you simply provide the 3D positions for the triangle's vertices within the Gui's 3D coordinate system. Remember that when using this function, the Z axis will be up.
Draw layers
Each shape you draw in a Gui has a "draw layer" that controls the way it overlaps with other shapes in the same Gui. Shapes with higher draw layer values are rendered in front of shapes with lower draw layer values, regardless of the placement of those shapes within the Gui's coordinate system.
When you use a plain 2D shape function, you can set the draw layer in the Z axis coordinate of the vector you pass for the shape's position in the Gui's drawing plane.
When you use a _3d shape function, you set the draw layer in a separate parameter. (The Z component of a _3d shape's position actually displaces that shape into or above its drawing plane -- see above.)
Immediate and retained mode
You can create your Gui in either immediate mode or retained mode.
In immediate mode, the Gui starts each frame by clearing away all shapes from the last frame. Each frame, you need to re-draw all the shapes that you want to be visible in that frame.
In retained mode, the Gui remembers each shape that you give it, and continues to draw those shapes every frame until you tell it to stop. When you create a shape, the Gui returns an integer that uniquely identifies that shape. If you need to change any attributes of the shape, you can pass this ID to one of the Gui update functions, along with the attributes you need to change. When you no longer need the Gui to show that shape, you pass the ID to one of the Gui destroy functions.
Examples
The Gui interface is very flexible, but it can be tricky to understand and to set up correctly. For some examples that show it in action, look through the Lua files under core/editor_slave/stingray_editor. Most of the gizmos and other debug rendering drawn by the Stingray editor in the viewport are done using Gui objects in world space, and the menus that you use to control viewport rendering options are done using screen-space Guis.
Constructors and accessors 
Related sample code
Other related reference items
Related help topics
Functions
 |
bitmap ( self, material, pos, size, color ) : integer Creates (or draws) a bitmap with the specified material.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
pos : | Specifies the position of the bitmap. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions of the bitmap. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
Other related reference items
| |
bitmap_3d ( self, material, tm, pos, layer, size, color ) : integerThis function is similar to Gui.bitmap(), but positions the object in 3D using the transform matrix (tm), so you can rotate the object freely in the 3D world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
With this function, you can use a single world gui to draw objects at different positions in the world.
Note: In this function, the layer is specified separately from the position, so you can use the z-coordinate of the position to offset the depth of the object.
| |
bitmap_3d_uv ( self, material, uv_00, uv_11, tm, pos, layer, size, color ) : integerThis function is similar to Gui.bitmap_uv(), but positions the object in 3D using the transform matrix (tm), so you can rotate the object freely in the 3D world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
uv_00 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
uv_11 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
With this function, you can use a single world gui to draw objects at different positions in the world.
Note: In this function, the layer is specified separately from the position, so you can use the z-coordinate of the position to offset the depth of the object.
| |
bitmap_uv ( self, material, uv_00, uv_11, pos, size, color ) : integerCreates (or draws) a bitmap using the specified UV-coordinates for the top left and bottom right corner.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
uv_00 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
uv_11 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
pos : | Specifies the position of the bitmap. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
Other related reference items
| |
create_material ( self, material ) : stingray.MaterialCreates a new material of the specified type, and assigns it to this Gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | string | Specifies the name of the .material resource file. |
|
The newly created Material object. |
| |
destroy_bitmap ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_bitmap_3d ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_rect ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_rect_3d ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_text ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_text_3d ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_triangle ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_video ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
destroy_video_3d ( self, id )In the retained mode, this function destroys the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
| This function does not return any values. |
| |
get_id ( self ) : integerReturns the a unique ID (per world) for that Gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. |
integer |
Returns the a unique ID (per world) for that Gui |
| |
has_all_glyphs ( self, text, font ) : booleanReturns true if the font has all the glyphs in the specified text.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
text : | string | Specifies the text. |
font : | string | Specifies the name of the font. |
boolean |
Returns true if the font has all the glyphs in the specified text. |
| |
has_video_player ( ) : stringReturns "IVF", or nil depending on what video library was linked with the engine.
|
| This function does not accept any parameters. |
string |
Returns "IVF", or nil. |
| |
material ( self, material ) : stingray.MaterialReturns the material assigned to this Gui from the specified .material resource file.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | string | Specifies the name of the .material resource file. |
|
A Material object that represents the material with the specified name. |
| |
move ( self, pose )Moves a world-positioned Gui object to a different position and rotation in the 3D game world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
pose : | The new translation and rotation of the bottom left corner of the Gui. |
| This function does not return any values. |
| |
move ( self, x, y )Moves a screen-positioned Gui object to a different position in the X,Y screen space.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
x : | number | The new horizontal position of the bottom left corner of the Gui. |
y : | number | The new vertical position of the bottom left corner of the Gui. |
| This function does not return any values. |
| |
rect ( self, pos, size, color, material ) : integerCreates (or draws in the immediate mode) a rectangle in the gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
pos : | The pos parameter is a Vector3 that specifies the position of the rectangle. (x,y) are the x and y coordinates and z is an integer specifying the draw layer. Objects with a high value of z appear in front of other objects. | |
size : | The size parameter is a Vector2 that specifies the dimensions of the rectangle. | |
color : | Optional. Specifies the color of the rectangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
material : | any(string, stingray.Material*)? | Optional. Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id for identifying the rectangle. |
This function returns an id for identifying the rectangle. This id is only useful in the retained mode.
Other related reference items
| |
rect ( self, pos, size, color, material ) : integerCreates (or draws in the immediate mode) a rectangle in the gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
pos : | The pos parameter is a Vector2 that specifies the position of the rectangle. (x,y) are the x and y coordinates. The draw layer is set to 0. | |
size : | The size parameter is a Vector2 that specifies the dimensions of the rectangle. | |
color : | Optional. Specifies the color of the rectangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
material : | any(string, stingray.Material*)? | Optional. Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id for identifying the rectangle. |
This function returns an id for identifying the rectangle. This id is only useful in the retained mode.
| |
rect_3d ( self, tm, pos, layer, size, color, material ) : integerThis function is similar to Gui.rect(), but positions the object in 3D using the transform matrix (tm), so you can rotate the object freely in the 3D world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | The pos parameter is a Vector3 that specifies the position of the rectangle. | |
layer : | integer | Specifies the layer. |
size : | The size parameter is a Vector2 that specifies the dimensions of the rectangle. | |
color : | Optional. Specifies the color of the rectangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
material : | any(string, stingray.Material*)? | Optional. Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id for identifying the rectangle. |
With this function, you can use a single world gui to draw objects at different positions in the world.
Note: In this function, the layer is specified separately from the position, so you can use the z-coordinate of the position to offset the depth of the object.
Other related reference items
| |
reset ( self )Clears the primitives in the Gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
This is automatically done at the end of every frame so calling this function is generally not needed. In the case where you render the world this gui resides in several times during a single frame, and want to draw different Gui primitives, calling this function is needed in between the calls to Application.render_world().
| |
resolution ( viewport, window ) : number, numberReturns the width and height of pixels that can be used in a screen gui when rendering into the specified viewport.
|
viewport : | Optional. The viewport whose resolution will be returned. If omitted, the back buffer resolution is returned. See Application.back_buffer_size(). The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
window : | Optional. Only used when rendering into multiple swap chains on PC. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
number |
The width (in pixels) that can be used when rendering to the specified viewport. |
number |
The height (in pixels) that can be used when rendering to the specified viewport. |
This is normally the same as Application.back_buffer_size(). The two values differ if the screen has non-square pixels or the output render target of the viewport is not the same as the back buffer. In that case, the Gui pixels are stretched horizontally to ensure that a Gui object with size (100,100) is still a perfect square. This means that there will be fewer or more Gui pixels horizontally than actual screen pixels.
Related sample code
| |
text ( self, text, font, font_size, material, pos, color, options ) : integerDraws a single line of text.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
text : | string | Specifies the string to draw. |
font : | string | Specifies the name of the font. |
font_size : | number | Specifies the size of the font in pixels. It must match the font size used to generate the font for pixel perfect drawing. |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
pos : | Specifies the position of the text. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
options : | string? | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
You cannot break the line using \n or other line break characters. If you need to create additional lines of text, you must call text() multiple times with different positions.
Related sample code
Other related reference items
| |
texture_size ( resource_name ) : number, numberGets the width and height of a texture resource.
|
resource_name : | string | The name of the texture resource. |
number |
Returns the width of a loaded texture. |
number |
Returns the height of a loaded texture. |
This function is only available in development builds.
| |
text_3d ( self, text, font, font_size, material, tm, pos, layer, color, options ) : integerThis function is similar to Gui.text(), but positions the object in 3D using the transform matrix (tm), so you can rotate the object freely in the 3D world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
text : | string | Specifies the string to draw. |
font : | string | Specifies the name of the font. |
font_size : | number | Specifies the size of the font in pixels. It must match the font size used to generate the font for pixel perfect drawing. |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
options : | string? | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
With this function, you can use a single world gui to draw objects at different positions in the world.
Note: In this function, the layer is specified separately from the position, so you can use the z-coordinate of the position to offset the depth of the object.
| |
text_extents ( self, text, font, font_size, options ) : stingray.Vector2, stingray.Vector2, stingray.Vector2Computes the extents of the text when drawn using the specified font and font_size.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
text : | string | Specifies the text. |
font : | string | Specifies the name of the font. |
font_size : | number | Specifies the size of the font in pixels. |
options : | any(string, number)* | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type. |
|
min. Describes the minimum x and y positions of any character in the drawn text. | |
|
max. Describes the maximum x and y positions of any character in the drawn text. | |
|
caret. Describes the position of the caret after drawing the text (where the next character must be placed). |
You can use this function to center or right-align the text.
Related sample code
| |
triangle ( self, p1, p2, p3, layer, color, material, uv0, uv1, uv2 ) : integerCreates (or draws) a triangle in the gui.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
p1 : | The Vector3 position of a triangle corner. | |
p2 : | The Vector3 position of a triangle corner. | |
p3 : | The Vector3 position of a triangle corner. | |
layer : | integer | Specifies the layer. |
color : | Optional. Specifies the color of the triangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
material : | string? | Optional. Specifies the name of the .material resource file to use. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
uv0 : | Optional. The UV-coordinate of a triangle corner. If you specify uv0, make sure to also specify the other two UV-coordinates: uv1 and uv2. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
uv1 : | Optional. The UV-coordinate of a triangle corner. If you specify uv1, make sure to also specify the other two UV-coordinates: uv0 and uv2. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
uv2 : | Optional. The UV-coordinate of a triangle corner. If you specify uv2, make sure to also specify the other two UV-coordinates: uv0 and uv1. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id for identifying the triangle. |
The p1, p2, and p3 arguments are the Vector3 positions of the triangle's corners. If specified, uv0, uv1, and uv2 give the UV-coordinates of the triangle's corners.
Note: The triangle function uses real 3D-coordinates, and not the 2D x-y coordinates like most of the other functions in the GUI. This means that instead of the y-coordinate, the z-coordinate represents up in the GUI and that the layer is specified using a separate parameter.
| |
update_bitmap ( self, id, material, pos, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies the name of the .material resource file to use. |
pos : | Specifies the position of the bitmap. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions of the bitmap. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_bitmap_3d ( self, id, material, tm, pos, layer, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies either the name of the .material resource file or a material pointer to use. |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_bitmap_3d_uv ( self, id, material, uv_00, uv_11, tm, pos, layer, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies the name of the .material resource file to use. |
uv_00 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
uv_11 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_bitmap_uv ( self, id, material, uv_00, uv_11, pos, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies the name of the .material resource file to use. |
uv_00 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
uv_11 : | Specifies the UV-coordinate. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
pos : | Specifies the position of the bitmap. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_rect ( self, id, pos, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
pos : | The pos parameter is a Vector3 that specifies the position of the rectangle. (x,y) are the x and y coordinates and z is an integer specifying the draw layer. Objects with a high value of z appear in front of other objects. | |
size : | The size parameter is a Vector2 that specifies the dimensions of the rectangle. | |
color : | Optional. Specifies the color of the rectangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_rect_3d ( self, id, tm, pos, layer, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | The pos parameter is a Vector3 that specifies the position of the rectangle. | |
layer : | integer | Specifies the layer. |
size : | The size parameter is a Vector2 that specifies the dimensions of the rectangle. | |
color : | Optional. Specifies the color of the rectangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_text ( self, id, text, font, material, font_size, pos, color, options )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
text : | string | Specifies the string to draw. |
font : | string | Specifies the name of the font. |
material : | string | Specifies the name of the .material resource file to use. |
font_size : | number | Specifies the size of the font in pixels. It must match the font size used to generate the font for pixel perfect drawing. |
pos : | Specifies the position of the text. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
options : | string? | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_text_3d ( self, id, text, font, material, font_size, tm, pos, layer, color, options )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
text : | string | Specifies the string to draw. |
font : | string | Specifies the name of the font. |
material : | string | Specifies the name of the .material resource file to use. |
font_size : | number | Specifies the size of the font in pixels. It must match the font size used to generate the font for pixel perfect drawing. |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. | |
options : | string? | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_triangle ( self, id, p1, p2, p3, layer, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
p1 : | The Vector3 position of a triangle corner. | |
p2 : | The Vector3 position of a triangle corner. | |
p3 : | The Vector3 position of a triangle corner. | |
layer : | integer | Specifies the layer |
color : | Optional. Specifies the color of the triangle. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_video ( self, id, material, video_player, pos, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies the name of the .material resource file to use. |
video_player : | video_player is a reference to the VideoPlayer whose video this Gui object must display. | |
pos : | Specifies the position of the video. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
update_video_3d ( self, id, material, video_player, tm, pos, layer, size, color )In the retained mode, this function updates the object with the specified id.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
id : | integer | Specifies the id of the object. |
material : | string | Specifies the name of the .material resource file to use. |
video_player : | video_player is a reference to the VideoPlayer whose video this Gui object must display. | |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
video ( self, material, video_player, pos, size, color ) : integerCreates a rectangle that draws a video.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
video_player : | video_player is a reference to the VideoPlayer whose video this Gui object must display. | |
pos : | Specifies the position of the video. If you pass a Vector3, the z component is an integer that specifies the draw layer. Objects with a higher draw layer value appear in front of other objects. If you pass a Vector2, the draw layer is set to 0. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. | |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
The video is drawn using the specified material. The material must use a custom shader that does YUV to RBG conversion. Otherwise, strange output from the video is seen. You can use the functions in the VideoPlayer to control the video playback.
Other related reference items
| |
video_3d ( self, material, video_player, tm, pos, layer, size, color ) : integerThis function is similar to Gui.video(), but positions the object in 3D using the transform matrix (tm), so you can rotate the object freely in the 3D world.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
material : | any(string, stingray.Material*) | Specifies either the name of the .material resource file or a material pointer to use. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. |
video_player : | video_player is a reference to the VideoPlayer whose video this Gui object must display. | |
tm : | Transform matrix. Positions the object in 3D. | |
pos : | Specifies the position. | |
layer : | integer | Specifies the layer. |
size : | Specifies the dimensions. | |
color : | Optional. Specifies the color. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Returns an id. |
With this function, you can use a single world gui to draw objects at different positions in the world.
Note: In this function, the layer is specified separately from the position, so you can use the z-coordinate of the position to offset the depth of the object.
| |
word_wrap ( self, text, font, font_size, width, whitespace, soft_dividers, return_dividers, options ) : tableReturns a list of strings that are divided in such a way that each string fits within the specified width.
|
self : | Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation. | |
text : | string | Specifies the text. |
font : | string | Specifies the name of the font. |
font_size : | number | Specifies the size of the font in pixels. |
width : | number | Specifies the width. |
whitespace : | string | A string of whitespace characters. Typically, it is " ". |
soft_dividers : | string | A string of characters that breaks a line if no whitespace exists on a string that needs to be divided. Typically, it is something like "-+&/". |
return_dividers : | string | A string with characters that forces a line break. Typically, it is "\n". |
options : | string? | Optional. Specifies additional options for the text. Each option is a string that identifies the option, followed by the value to set for that option. Supported options are:
The ? notation indicates that this type is optional: there may be zero or one instances of it. |
table |
Returns a list of strings. |