Module Drawing
Functions for drawing images and text.
See here for more information: link
Functions
| allocateFrameType () | Allocates a free frame type integer for use with Drawing.setFrameType. |
| drawImage (frame, x, y) | Draws a frame. |
| drawImageRect (frame, x, y, w, h) | Draws a frame into a specified rectangle. |
| drawLine (x0, y0, x1, y1[, width=1]) | Draws a line. |
| drawNinePatch (frame, x, y, w, h[, sparse=false]) | Draws a nine patch into a specified rectangle. |
| drawQuad (x0, y0, x1, y1, x2, y2, x3, y3[, frame=nil]) | Draws a quad using four corner points. |
| drawRect (x, y, w, h) | Draws a filled rectangle. |
| drawText (text, x, y[, font=nil[, centerX=0[, centerY=0]]]) | Draws a text. |
| drawTileImage (frame) | Draws a tile frame on the currently set tile. |
| drawTriangle (x0, y0, x1, y1, x2, y2[, frame=nil]) | Draws a triangle. |
| flush () | Flushes the drawing pipeline. |
| getAdditive () | Returns the current additive factor for drawing. |
| getAlpha () | Returns the current transparency for drawing. |
| getColor () | Returns the current drawing color. |
| getDaytime () | Returns the current part of the "visual day" with 0.5 being noon. |
| getDaytimeColor () | Returns the shading color that is used for the current day time. |
| getFrameType () | Gets the currently set frame type. |
| getImageHandle (frame) | Returns the handle of an image/frame. |
| getImageSize (frame) | Returns the size of an image/frame. |
| getScale () | Returns the current scale factors set by setScale. |
| getSize () | Returns the current screen size width, height in pixels. |
| getTextSize (text[, font=nil]) | Queries the drawing size for a given text. |
| reset () | Resets all drawing properties. |
| resetClipping () | Resets clipping so that draw functions affect all pixels again. |
| setAdditive (additive) | Sets the additive factor used for additive drawing. |
| setAlpha (alpha) | Sets the transparency for drawing. |
| setClipping (x, y, w, h) | Sets the clipping rect to a specified rectangle. |
| setColor (r, g, b) | Sets the drawing color. |
| setFrameType (frameType) | Sets a frame type that will be applied to the next drawn frames. |
| setScale (scaleX, scaleY) | Sets the scale for drawing (absolute). |
| setTile (tileX, tileY[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]]) | Sets the current drawing offset and scale to a certain tile on the map. |
| setUniform (name, v0[, v1[, v2[, v3]]]) | Sets a uniform float vector that can be used in shaders. |
Functions
- allocateFrameType ()
-
Allocates a free frame type integer for use with Drawing.setFrameType.
You should only call this function once during the lifecycle of the game to
prevent clutter.
New feature:
-
This is a new feature that was added in version 1.10.91
Returns:
-
int
A fresh frame type identifier.
- drawImage (frame, x, y)
-
Draws a frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- drawImageRect (frame, x, y, w, h)
-
Draws a frame into a specified rectangle.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- drawLine (x0, y0, x1, y1[, width=1])
-
Draws a line.
Parameters:
- x0 number X component of the start point.
- y0 number Y component of the start point.
- x1 number X component of the end point.
- y1 number Y component of the end point.
- width number The width of the line. (default 1)
- drawNinePatch (frame, x, y, w, h[, sparse=false])
-
Draws a nine patch into a specified rectangle. A nine patch is a set of
9 frames that are used to draw a rectangle with borders. All parts expect
the corners are streched to match accordingly.
Parameters:
- frame integer or draft The base frame of the nine patch.
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- sparse boolean If true the center frame will not be drawn. (default false)
- drawQuad (x0, y0, x1, y1, x2, y2, x3, y3[, frame=nil])
-
Draws a quad using four corner points.
If no frame is provided a white quad will be drawn.
New feature:
-
This is a new feature that was added in version 1.10.22
Parameters:
- x0 number X component of the first point.
- y0 number Y component of the first point.
- x1 number X component of the second point.
- y1 number Y component of the second point.
- x2 number X component of the third point.
- y2 number Y component of the third point.
- x3 number X component of the fourth point.
- y3 number Y component of the foruth point.
- frame integer or draft A frame or draft (that contains at least one frame). (default nil)
- drawRect (x, y, w, h)
-
Draws a filled rectangle.
Parameters:
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- drawText (text, x, y[, font=nil[, centerX=0[, centerY=0]]])
-
Draws a text.
Parameters:
- text string The text to draw.
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- font font The font to use. (default nil)
- centerX number The relative x center for the pivot point (usually ranges from 0 to 1; 0.5 would be the center of the text). (default 0)
- centerY number The relative y center for the pivot point (usually ranges from 0 to 1; 0.5 would be the center of the text). (default 0)
- drawTileImage (frame)
-
Draws a tile frame on the currently set tile. A tile frame is supposed
to lay flat on the ground. The magic of this function is to draw the frame
correctly on slopes. Use this function e.g. for drawing tool markers
on the ground.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- drawTriangle (x0, y0, x1, y1, x2, y2[, frame=nil])
-
Draws a triangle. If no frame is provided a white triangle will be drawn.
As the game is optimized to draw quads it is more efficient to draw a quad
using Drawing.drawQuad rather than drawing two triangles.
Parameters:
- x0 number X component of the first point.
- y0 number Y component of the first point.
- x1 number X component of the second point.
- y1 number Y component of the second point.
- x2 number X component of the third point.
- y2 number Y component of the third point.
- frame integer or draft A frame or draft (that contains at least one frame). (default nil)
- flush ()
-
Flushes the drawing pipeline. Can be used to synchronize when things are
drawn. Normally frames are drawn in large batches for better performance.
New feature:
-
This is a new feature that was added in version 1.10.85
- getAdditive ()
-
Returns the current additive factor for drawing.
Returns:
-
number
Additive factor ranging from 0 (not additive) to 1 (fully additive).
- getAlpha ()
-
Returns the current transparency for drawing.
Returns:
-
number
Transparency value ranging from 0 (transparent) to 1 (opaque).
- getColor ()
-
Returns the current drawing color.
Returns:
- integer Red comoponent of the drawing color.
- integer Green comoponent of the drawing color.
- integer Blue comoponent of the drawing color.
- getDaytime ()
-
Returns the current part of the "visual day" with 0.5 being noon.
New feature:
-
This is a new feature that was added in version 1.10.49
Returns:
-
number
A number 0..1 representing the visual day.
- getDaytimeColor ()
-
Returns the shading color that is used for the current day time.
New feature:
-
This is a new feature that was added in version 1.10.49
Returns:
-
int,int,int
Three integers that represent the shading color.
- getFrameType ()
-
Gets the currently set frame type.
The frame type is a 0-255 integer number that can be accessed from within
the shader. The values 0-64 can be considered as reserved by the game.
New feature:
-
This is a new feature that was added in version 1.10.91
Returns:
-
int
The currently set frame type.
- getImageHandle (frame)
-
Returns the handle of an image/frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame) for which the handle location will be queried.
Returns:
- number X handle of the frame (in pixels).
- number y handle of the frame (in pixels).
- getImageSize (frame)
-
Returns the size of an image/frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame) for which the size will be queried.
Returns:
- number Width of the frame (in pixels).
- number Height of the frame (in pixels).
- getScale ()
-
Returns the current scale factors set by setScale.
Returns:
- number Scaling factor for x axis.
- number Scaling factor for y axis.
- getSize ()
-
Returns the current screen size width, height in pixels.
Note that the result may change over time due to resolution changes.
Returns:
-
number,
number
- getTextSize (text[, font=nil])
-
Queries the drawing size for a given text.
Parameters:
- text string The text to calculate the size of (in pixels).
- font font The font to calculate the size for. (default nil)
Returns:
- number Width required to draw the text.
- number Height required to draw the text.
- reset ()
- Resets all drawing properties. It's good practice to call this function before using other Drawing functions.
- resetClipping ()
- Resets clipping so that draw functions affect all pixels again.
- setAdditive (additive)
-
Sets the additive factor used for additive drawing. Additive drawing
simply adds the colors to the background instead of mixing them.
Parameters:
- additive number The additivity factor to use. 0 being non additive, 1 being fully additive.
- setAlpha (alpha)
-
Sets the transparency for drawing.
Parameters:
- alpha number The transparency to use. 0 being fully transparent, 1 being fully opaque.
- setClipping (x, y, w, h)
-
Sets the clipping rect to a specified rectangle.
Consecutive calls to drawing functions will only afftect pixels
within that rectangle.
Parameters:
- x number The x coordinate for clipping.
- y number The y coordinate for clipping.
- w number The width for clipping.
- h number The height for clipping.
- setColor (r, g, b)
-
Sets the drawing color. Component values range from 0 to 255 with 0,0,0
being black and 255,255,255 being white.
When drawing things the drawing color is applied in a multiplicative way.
So using white as drawing color won't alter the color of images when drawing.
Parameters:
- r integer Red component of the color.
- g integer Green component of the color.
- b integer Blue component of the color.
- setFrameType (frameType)
-
Sets a frame type that will be applied to the next drawn frames.
The frame type is a 0-255 integer number that can be accessed from within
the shader. The values 0-64 can be considered as reserved by the game.
It is good practice to set the frame type to the previous value after you
are done with it.
You should only use frame types that are either defined by the game or
were previously allocated using Drawing.allocateFrameType().
If you try to draw frames whose Draft:getFrameType is non zero that frame
type will be used instead.
New feature:
-
This is a new feature that was added in version 1.10.91
Parameters:
- frameType int The frame type to set.
Returns:
-
int
The previously set frame type.
- setScale (scaleX, scaleY)
-
Sets the scale for drawing (absolute). 1 for both of them would mean no
scaling at all while values greater than 1 will scale things up. values
smaller than 1 will draw things smaller.
Parameters:
- scaleX number Scaling factor for x axis.
- scaleY number Scaling factor for y axis.
- setTile (tileX, tileY[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]])
-
Sets the current drawing offset and scale to a certain tile on the map.
Parameters:
- tileX integer X coordinate of the tile.
- tileY integer Y coordinate of the tile.
- offsetX number X offset for drawing (in pixels). (default 0)
- offsetY number Y offset for drawing (in pixels). (default 0)
- localScaleX number Additional scaling factor for x axis. (default 1)
- localScaleY number Additional scaling factor for y axis. (default 1)
- setUniform (name, v0[, v1[, v2[, v3]]])
-
Sets a uniform float vector that can be used in shaders.
A uniform vector can hold up to 4 entries.
If no entries are provided the uniform will be deleted.
New feature:
-
This is a new feature that was added in version 1.10.82
Parameters:
- name string The name of the uniform variable in the shader
- v0 float The first vector entry
- v1 float The second vector entry (optional)
- v2 float The third vector entry (optional)
- v3 float The fourth vector entry (optional)