Expand Up
@@ -589,6 +589,83 @@ For the following functions `x` can be either a vector or a number:
* `vector.multiply(v, x)`: returns a scaled vector or Schur product
* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
Relative Positions and Rectangles
---------------------------------
A relative position/rectangle is a position/rectangle that is relative to a parent rectangle.
It is a table, but the internal representation of this table can vary depending on what part
of the parent rectangle the position/rectangle should be relative to.
Relative positions/rectangles are based on zero, i.e. `{x=0, y=0}` is the top left position,
not `{x=1, y=1}`, as might be assumed with Lua.
The internal representation of a relative position table:
* For the X axis, either:
* `x`: Relative to the left side of the parent rectangle.
* `nx`: Relative to the right side of the parent rectangle.
* For the Y axis, either:
* `y`: Relative to the top side of the parent rectangle.
* `ny`: Relative to the bottom side of the parent rectangle.
A position that uses the components `x` and `y` is called a "standard position".
Examples: Positions relative to a rectangle with a width of 15 and a height of 6:
* `{x=5, y=3}`:
```
|
3
|
--5--X---------
|
|
```
* `{nx=7, y=1}`:
```
1
-------X---7---
|
|
|
|
```
The internal representation of a relative rectangle table:
* For the X axis, any two of:
* `w`: Defines the width of the rectangle.
* `x`: Defines the left side of the rectangle as relative to the left side of the parent
rectangle.
* `nx`: Defines the right side of the rectangle as relative to the right side of the
parent rectangle.
* For the Y axis, any two of:
* `h`: Defines the height of the rectangle.
* `y`: Defines the top side of the rectangle as relative to the top side of the parent
rectangle.
* `ny`: Defines the bottom side of the rectangle as relative to the bottom side of the
parent rectangle.
A rectangle that uses the components `x`, `y`, `w`, and `h` is called a "standard rectangle".
A rectangle that uses the components `x`, `y`, `nx`, and `ny` is called an "offset rectangle".
Examples: Rectangles relative to another rectangle with a width of 15 and a height of 6:
* `{x=3, y=1, w=4, h=3}`:
```
1
-3-XXXX--------
3 X
XX4X
|
|
```
* `{x=4, nx=4, y=1, ny=0}`:
```
1
--4-XXXXXXX-4--
X X
X X
X X
XXXXXXX
```
Helper functions
----------------
* `dump2(obj, name="_", dumped={})`
Expand Down
Expand Up
@@ -821,6 +898,67 @@ Call these functions only at load time!
* `minetest.localplayer`
* Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
### Rendering
Functions for texture drawing and rendering related functions.
* `minetest.register_on_predraw(function(dtime))`
* Called every frame right before the engine has started drawing. Code used here must be
fast to ensure the framerate doesn't drop.
* Mainly useful for updating or binding `Texture`s before the engine has started drawing.
* `dtime`: Time in seconds since the last frame.
* `minetest.register_on_draw(function(dtime))`
* Called every frame after the engine is finished drawing for custom drawing to the screen
Code used here must be fast to ensure the framerate doesn't drop.
* `dtime`: Time in seconds since the last frame.
* `minetest.on_next_predraw(function(dtime))`
* Called right before the next time `minetest.register_on_predraw` has started running.
* Calling this function inside itself will be run in the same predraw.
* Useful if something needs to be done inside a drawing callback once, e.g. drawing to a
`Texture`.
* `dtime`: Time in seconds since the previous frame.
* `minetest.on_next_draw(function(dtime))`
* Called right before the next time `minetest.register_on_draw` has started running.
* Calling this function inside itself will be run in the same draw.
* Useful if something needs to be done inside a drawing callback once, e.g. drawing to a
`Texture`.
* `dtime`: Time in seconds since the previous frame.
* `minetest.get_driver_info()` -> info: Returns a table containing information about and the
limitations of the current video driver.
* On lower end graphics cards, e.g. Android, some features may not be available. OpenGL,
the recommended driver for desktop computers, supports all these features.
* `info`: A table containing the information. Contains the following keys:
* `name`: Name of the current video driver. This string is the current `video_driver`
setting value. Possible values are "null", "software", "burningsvideo", "direct3d8",
"direct3d9", "opengl", "ogles1", or "ogles2".
* `friendly_name`: A more human readable name of the current driver.
* `render_textures`: True if the driver supports true hardware rendering to textures,
i.e. all the drawing and modification functions of `Texture`.
* `npot_textures`: True if the driver supports textures with dimensions that are not
powers of two, i.e. not just 16, 32, 64, 128, etc.
* `non_square_textures`: True if the driver supports non-square textures, i.e.
rectangular textures.
* `max_texture_size`: A 2D vector denoting the maximum texture size that can be used. If
`x` or `y` is `math.huge`, there is no limit.
* `minetest.get_optimal_texture_size(size[, pot][, square][, max_size][, smaller])` -> optimal_size:
Gets the best possible texture size given the specified driver limitations for textures.
* Unless otherwise specified, all optional arguments, if not provided or nil, default to
the current driver limitations found in `minetest.get_driver_info()`.
* `size`: A 2D vector that is the preferred texture size that will be modified.
* `pot` (optional): Whether the texture dimensions must be powers of two.
* `square` (optional): Whether the texture must be a square.
* `max_size` (optional): A 2D vector defining the maximum size that this texture may be. If
either dimension is `math.huge`, there is no limit.
* `smaller` (optional): If true and any texture dimensions do have to be changed, the texture
dimensions will be reduced instead of enlarged. Defaults to false. However, if the size
provided is larger than the maximum size, it will be reduced regardless of this setting.
* `optimal_value`: The optimal texture value given the provided constraints. If either
resulting dimension is zero, it will default to one.
* `minetest.window`: A special `Texture` that points to the Minetest window.
* The window is write-only and cannot contain alpha pixels.
* The screen supports all functions in `Texture` regardless of any driver limitations in
`minetest.get_driver_info` unless documented as otherwise.
### Privileges
* `minetest.get_privilege_list()`
* Returns a list of privileges the current player has in the format `{priv1=true,...}`
Expand Down
Expand Up
@@ -1152,6 +1290,139 @@ Can be obtained via `minetest.get_meta(pos)`.
* `fields`: key-value storage
* `inventory`: `{list1 = {}, ...}}`
`Texture`
---------
A Lua interface for interacting with hardware GPU textures.
All functions that draw to or create textures must be in a draw or predraw callback and (with
the exception of `minetest.window`) require the video driver to support render textures. See
`minetest.get_driver_info` for more information on the limitations of textures.
Unless otherwise specified, all positions and rectangles are relative to the `Texture` being
drawn to. See [Relative Positions and Rectangles].
### Constructors
* `Texture.new(size)` -> texture: Creates a blank `Texture`.
* `size`: 2D vector defining the size to make the `Texture`.
* Does not work if the driver doesn't support render textures. See
`minetest.get_driver_info`.
* Returns nil if the texture could not be created for some reason.
* `Texture.copy(texture)` -> texture: Returns a copy of another texture.
* `texture`: Either an in-game texture string or a `Texture` to copy. Must be readable.
* Returns nil if the texture could not be created for some reason.
* `Texture.ref(texture)` -> texture: Returns a reference to a texture.
* `texture`: Either an in-game texture string or a `Texture`.
* The resulting `Texture` object will point to the texture. Since it does not hold full
access to the texture, it is read-only.
* This is useful for getting attributes about any texture, e.g. the size, without making a full
copy, which is time consuming.
### Methods
* `is_readable()` -> bool: Returns whether the texture can be read from.
* `minetest.window` can not be read from.
* `is_writable()` -> bool: Returns whether the texture can be written to.
* Texture references cannot be written to.
* `get_size()` -> size: Returns a 2D vector of the size of the texture.
* This may not be the same as the provided size to `Texture.new` if the driver doesn't
support the specified texture size.
* `fill(color)`: Fills the entire texture with a certain color.
* Unlike `draw_rect`, this replaces the pixels completely instead of adding the alpha.
* `color`: The color to fill the texture with.
* The texture being filled must be writable.
* `draw_pixel(pos, color[, clip_rect])`: Draws a pixel.
* `pos`: A position to draw the pixel at. Where the pixel will be positioned from depends
on the relative position provided:
* `x`: Horizontal is positioned from left edge of pixel
* `nx`: Horizontal is positioned from right edge of pixel
* `y`: Vertical is positioned from top edge of pixel
* `ny`: Vertical is positioned from bottom edge of pixel
* `color`: Color of the pixel to draw.
* `clip_rect` (optional): If specified, the pixel will only be drawn if it is inside this
rectangle.
* The texture being drawn to must be writable.
* `draw_rect(rect, color[, clip_rect])`: Draws a filled rectangle.
* `rect`: The rectangle to draw.
* `color`: Can be one of two things:
* A single color: The whole rectangle will be filled with this color
* An array of four colors: The rectangle will be drawn with a gradient. Each corner is
assigned one of the colors. Index 1 is top-left, 2 is top-right, 3 is bottom-left,
and 4 is bottom-right.
* `clip_rect` (optional): If specified, any part of the filled rectangle that extends out
of this rectangle will not be drawn.
* The texture being drawn to must be writable.
* `draw_texture(rect, texture[, clip_rect][, source_rect][, recolor])`: Draws a 2D texture.
* `rect`: The rectangle to draw the texture in. The texture will be stretched to fit.
* `texture`: Either the name of the texture with optional texture modifiers or the
`Texture` object to draw. Must be readable. A texture may not draw itself to itself.
* `clip_rect` (optional): If specified, any part of the texture that extends out of this
rectangle will not be drawn.
* `source_rect` (optional): Defines a rectangular sub-texture of the texture which will be
drawn instead of the entire texture. If nil, the whole texture is drawn. This rectangle
is relative to the rectangle of the texture being drawn to.
* `recolor` (optional): The color to recolor the texture to when drawing. This uses
hardware coloring, so it uses color multiplication and is fast.
* The texture being drawn to must be writable.
* `draw_text(pos, text[, clip_rect][, font][, color])`: Draws text.
* Font shadows are not drawn for versatility's sake and must be drawn manually if desired.
* `pos`: The position of the top left of the text.
* `text`: The text to draw. Newlines and `'\0'` are converted to spaces. Color escape codes
are stripped.
* `clip_rect` (optional): If specified, any part of the text that extends out of this
rectangle will not be drawn.
* `font` (optional): The `Font` to draw with. Defaults to the default font.
* `color` (optional): The color to make the text. Default white.
* The texture being drawn to must be writable.
`Font`
------
A Lua representation of a font. This only includes data relevant to the font itself, and any
other effects, such as color, underlining, and font shadows, must be handled elsewhere.
### Constructor
* `Font([from])` -> font: Creates a font from another `Font` or a font table.
* `from`: Either another `Font`, a font table, or nothing.
* A font table has the following keys:
* `face`: The font face to use.
* Can be one of the following:
* "normal" (default): The default user-set font.
* "mono": A monospace font.
* If a client's locale requires the fallback font, the fallback font will be used
regardless of the font specified here.
* In general, the fallback font should only be explicitly specified if it is known
that characters not supported in many fonts will be used.
* `size`: What size the font should be. The default is user-set.
* It is highly recommended to make the font size relative to the user-set font size
to respect preferences and accessibility concerns.
* `bold`: Whether the text should be bold. Default false.
* Some fonts may not support bolded styles, in which case it falls back to not
bolded.
* `italic`: Whether the text should be italicized. Default false.
* Some fonts may not support italicized styles, in which case it falls back to not
italicized.
### Methods
* `get_metrics()` -> metrics: Get global font metrics in pixels.
* `metrics`: A table containing font metrics. It has the following keys:
* `height`: The height of text in this font.
* `line_height`: The distance from one baseline to the baseline on the next line.
* `baseline`: The distance to the baseline from the top of the text.
* `line_thickness`: The thickness of underlines and strikethroughs.
* `underline_pos`: The distance to the top of the underline from the top of the text.
* `strike_pos`: The distance to the top of the strikethrough from the top of the text.
* `get_text_width(text)` -> width: Gets the width of the specified text in pixels.
* `text`: The text to get the width of. Newlines and `'\0'` are converted to spaces. Color
escape codes are stripped.
* `to_table()` -> font_table: Returns this font as a font table.
* See the `Font` constructor for the keys in a font table.
* To get default user-set values for a font, do `Font():to_table()`, optionally specifying
the font face in the constructor to get the default values for that face.
### `Raycast`
A raycast on the map. It works with selection boxes.
Expand Down