Difference between revisions of "Lua API:Renderer"

From The Powder Toy
Jump to: navigation, search
(renderer.colourMode: the devil's in the details)
m (Remove old duplicate ren.decorations function documentation)
 
(8 intermediate revisions by 4 users not shown)
Line 49: Line 49:
 
  number ren.colorMode
 
  number ren.colorMode
 
  ren.colorMode(number colourMode)
 
  ren.colorMode(number colourMode)
 
A colour mode is basically a description of how particles are drawn. The other details which are considered when particles are drawn are fire mode, pixel mode and effect mode (rare cases like portals).
 
 
ren.'''COLOUR_BASC''', for example, draws every particle with its usual color (which I will here define as the Colour property of the element). It also disregards little details like the heat-glow of LAVA and metals.<br>
 
ren.'''COLOUR_HEAT''' disregards its usual color entirely and uses the heat map only. <br>
 
ren.'''COLOUR_GRAD''' kind of uses the usual colour of the element, except the colour is gradually turned brighter and then back to normal to create a gradient or stripy effect. <br>
 
ren.'''COLOUR_LIFE''' is the colour mode that gets applied when you use the 'Life display' render mode - it gets brighter the larger the life property of the particle is.<br>
 
ren.'''COLOUR_DEFAULT''' is the colour mode that occurs usually: in it things like lava and metal get an 'usual colour' that gets brighter when the element heats up.
 
  
 
This function takes one optional integer and sets which colour modes the currently appIying render mode uses. If the function is called with no arguments, it returns the current colour mode as an integer as well.
 
This function takes one optional integer and sets which colour modes the currently appIying render mode uses. If the function is called with no arguments, it returns the current colour mode as an integer as well.
  
=== renderer.colorMode ===
+
A colour mode is basically a description of how particles are drawn. The other details which are considered when particles are drawn are fire mode, pixel mode and effect mode (rare cases like portals).
number ren.colorMode()
 
ren.colorMode(number colorMode)
 
An alias for ren.colourMode.
 
  
=== renderer.decorations ===
+
On the bottom of this page there's [[#Color_modes|a list of descriptions]] of what each colour mode does.
number ren.decorations()
 
ren.decorations(number decoSetting)
 
If called with no arguments, returns a 0 or a 1 representing the current deco mode setting. If a number is passed in, turns decorations on or off.
 
  
 
=== renderer.grid ===
 
=== renderer.grid ===
Line 76: Line 62:
  
 
If an argument is passed in, sets the current grid size. There are no checks to make sure it is in the valid range, but if negative numbers are passed in it may cause strange behavior.
 
If an argument is passed in, sets the current grid size. There are no checks to make sure it is in the valid range, but if negative numbers are passed in it may cause strange behavior.
 +
 +
=== renderer.hud ===
 +
Controls if the hud is shown or not.
 +
 +
<pre>renderer.hud(enabled)
 +
enabled = renderer.hud()</pre>
 +
* <code>enabled</code>: boolean flag that specifies if the HUD is enabled or not.
  
 
=== renderer.debugHUD ===
 
=== renderer.debugHUD ===
Line 81: Line 74:
 
  ren.debugHUD(number debugSetting)
 
  ren.debugHUD(number debugSetting)
 
If called with no arguments, returns a 0 or a 1 representing whether the debug HUD (normally set with 'd') is on or off. If a number is passed in, turns the debug HUD on or off.
 
If called with no arguments, returns a 0 or a 1 representing whether the debug HUD (normally set with 'd') is on or off. If a number is passed in, turns the debug HUD on or off.
 +
 +
=== renderer.showBrush ===
 +
number ren.showBrush()
 +
ren.showBrush(number brushSetting)
 +
If called with no arguments, returns a 0 or a 1 representing whether the brush is currently shown. If a number is passed in, disables rendering the brush. This function is intended for recording scripts which want to hide the brush and other hud elements.
 +
 +
=== renderer.zoomEnabled ===
 +
ren.zoomEnabled(bool zoomState)
 +
bool ren.zoomEnabled()
 +
If called with no arguments, returns a boolean indicating whether the zoom window is open or not. 
 +
If a number is passed in, it shows or hides the zoom window.
 +
 +
=== renderer.zoomScope ===
 +
number, number, number ren.zoomScope()
 +
ren.zoomScope(number x, number y, number size)
 +
The zoom scope defines the area where to zoom in.
 +
If called with no arguments, returns 3 numbers: left top corner X position, left top corner Y position and its size. 
 +
If arguments are passed then the zoom scope will be moved to the specified X and Y coordinates (from its top left corner). It will also make it span the amount of pixels specified by the 'size' argument equally in width and height.
 +
 +
=== renderer.zoomWindow ===
 +
number, number, number, number ren.zoomWindow()
 +
ren.zoomWindow(number x, number y, number zoomFactor)
 +
The zoom window displays the magnified image.
 +
If called with no arguments, returns 4 numbers: left top corner X position, left top corner Y position, the zoom factor and the inner window size in pixels. 
 +
If arguments are passed then the zoom window will be moved to the specified X and Y coordinates (from its top left corner) and change its zoom factor.
 +
 +
=== renderer.decorations ===
 +
 +
Controls whether the decorations layer is enabled.
 +
 +
<pre>renderer.decorations(enabled)
 +
enabled = renderer.decorations()</pre>
 +
* <code>enabled</code>: boolean true/false flag that specifies whether deco is on or off.
 +
 +
=== renderer.fireSize ===
 +
 +
Controls intensity of fire effects. The default is 1. Other values may cause glitchy graphics such as CELL borders appearing in fire effects.
 +
 +
<pre>renderer.fireSize(size)
 +
size = renderer.fireSize()</pre>
 +
* <code>size</code>: floating point value that specifies the fire intensity.
 +
 +
=== renderer.useDisplayPreset ===
 +
 +
Loads a standard display preset, as if you pressed a number key.
 +
 +
<pre>renderer.useDisplayPreset(preset)</pre>
 +
* <code>preset</code>: The preset to enable.
 +
 +
Presets start at 0, so preset 0 is velocity display, and preset 3 is fire display. Most presets match the order of the in-game shortcuts, except for life gradient display - preset 9, and alternate velocity display - preset 10.
  
 
== Constants ==
 
== Constants ==
Line 171: Line 214:
 
|FIRE_BLEND
 
|FIRE_BLEND
 
|0x00020000
 
|0x00020000
|Adds a stronger fire effect around an element. All gasses have this on by default.
+
|Adds a strong fire effect around an element. All gasses have this on by default.
 +
|-
 +
|FIRE_SPARK
 +
|0x00040000
 +
|Adds a moderate fire effect around an element. Used by SPRK.
 
|-
 
|-
 
|
 
|
Line 276: Line 323:
 
|}
 
|}
  
 +
=== Color modes ===
 +
These are the values used and returned by ren.colorMode. Only one can be set at a time, and they control which types of colors particles are drawn in.
 +
{| class="wikitable"
 +
|-
 +
|<b>name</b>
 +
|<b>description</b>
 +
|-
 +
|COLOUR_DEFAULT
 +
|Default colors, nothing gets changed.
 +
|-
 +
|COLOUR_HEAT
 +
|Render elements in heat display colors. Pink = hottest, Blue = coldest.
 +
|-
 +
|COLOUR_LIFE
 +
|Render elements in a greyscale gradient dependent on .life value.
 +
|-
 +
|COLOUR_GRAD
 +
|Render elements normally, but with a slight greyscale gradient dependent on a particle's temperature.
 +
|-
 +
|COLOUR_BASC
 +
|Remove all color changes from elements, elements get rendered in whichever color their element button is.
 +
|-
 +
|}
 
[[Category:Lua]]
 
[[Category:Lua]]

Latest revision as of 23:06, 28 March 2024

The renderer api can be used to control how the simulation in TPT gets rendered. You can set render / display modes, and change things related to the HUD / grid mode. Some renderer related functions are in the legacy tpt.* api.

ren.* is an alias for renderer.* and can be used to write things shorter.

Methods

renderer.renderModes

table ren.renderModes()
ren.renderModes(table newModes)

If called with no arguments, returns a table containing the currently activated render modes. If called with a table argument, turns on all the render modes specified in the table. Render modes are typically used to change the way all particles render, display modes set extra added effects.

Print out all current render modes in hex:

for k,v in pairs(ren.renderModes()) do
    print(k,"0x"..bit.tohex(v))
end
>>1, 0x00fff380; 2, 0xff00f270; 3, 0x0400f381


Set the current render mode to a weird form of blob display

ren.renderModes({ren.RENDER_BLOB, ren.RENDER_EFFE})

renderer.displayModes

table ren.displayModes()
ren.displayModes(table newModes)

Works exactly like rennder.renderModes(). If called with no arguments, returns a table containing the currently activated display modes. If called with a table argument, turns on all the display modes specified in the table. Render modes are typically used to change the way all particles render, display modes set extra added effects.

Print out all current display modes in hex:

for k,v in pairs(ren.displayModes()) do
    print(k,"0x"..bit.tohex(v))
end
>>1, 0x00000002; 2, 0x00000010


Set the current display mode to persistent with cracker velocity display

ren.displayModes({ren.DISPLAY_AIRC, ren.DISPLAY_PERS})

renderer.colourMode

number ren.colourMode()
ren.colourMode(number colourMode)
number ren.colorMode
ren.colorMode(number colourMode)

This function takes one optional integer and sets which colour modes the currently appIying render mode uses. If the function is called with no arguments, it returns the current colour mode as an integer as well.

A colour mode is basically a description of how particles are drawn. The other details which are considered when particles are drawn are fire mode, pixel mode and effect mode (rare cases like portals).

On the bottom of this page there's a list of descriptions of what each colour mode does.

renderer.grid

number ren.grid()
ren.grid(number gridSize)

If called with no arguments, returns the current grid size (normally set with 'g'). Grid sizes range from 0 (no grid) to 9. Each size increases the number of pixels between lines by 4.

If an argument is passed in, sets the current grid size. There are no checks to make sure it is in the valid range, but if negative numbers are passed in it may cause strange behavior.

renderer.hud

Controls if the hud is shown or not.

renderer.hud(enabled)
enabled = renderer.hud()
  • enabled: boolean flag that specifies if the HUD is enabled or not.

renderer.debugHUD

number ren.debugHUD()
ren.debugHUD(number debugSetting)

If called with no arguments, returns a 0 or a 1 representing whether the debug HUD (normally set with 'd') is on or off. If a number is passed in, turns the debug HUD on or off.

renderer.showBrush

number ren.showBrush()
ren.showBrush(number brushSetting)

If called with no arguments, returns a 0 or a 1 representing whether the brush is currently shown. If a number is passed in, disables rendering the brush. This function is intended for recording scripts which want to hide the brush and other hud elements.

renderer.zoomEnabled

ren.zoomEnabled(bool zoomState)
bool ren.zoomEnabled()

If called with no arguments, returns a boolean indicating whether the zoom window is open or not. If a number is passed in, it shows or hides the zoom window.

renderer.zoomScope

number, number, number ren.zoomScope()
ren.zoomScope(number x, number y, number size)

The zoom scope defines the area where to zoom in. If called with no arguments, returns 3 numbers: left top corner X position, left top corner Y position and its size. If arguments are passed then the zoom scope will be moved to the specified X and Y coordinates (from its top left corner). It will also make it span the amount of pixels specified by the 'size' argument equally in width and height.

renderer.zoomWindow

number, number, number, number ren.zoomWindow()
ren.zoomWindow(number x, number y, number zoomFactor)

The zoom window displays the magnified image. If called with no arguments, returns 4 numbers: left top corner X position, left top corner Y position, the zoom factor and the inner window size in pixels. If arguments are passed then the zoom window will be moved to the specified X and Y coordinates (from its top left corner) and change its zoom factor.

renderer.decorations

Controls whether the decorations layer is enabled.

renderer.decorations(enabled)
enabled = renderer.decorations()
  • enabled: boolean true/false flag that specifies whether deco is on or off.

renderer.fireSize

Controls intensity of fire effects. The default is 1. Other values may cause glitchy graphics such as CELL borders appearing in fire effects.

renderer.fireSize(size)
size = renderer.fireSize()
  • size: floating point value that specifies the fire intensity.

renderer.useDisplayPreset

Loads a standard display preset, as if you pressed a number key.

renderer.useDisplayPreset(preset)
  • preset: The preset to enable.

Presets start at 0, so preset 0 is velocity display, and preset 3 is fire display. Most presets match the order of the in-game shortcuts, except for life gradient display - preset 9, and alternate velocity display - preset 10.

Constants

Any of these constants can be accessed with renderer.<constant name here>

Particle graphics function modes

These should be used in lua graphics functions to set how particles will be drawn. Effects like fire, glowing, and flares are set here. How a particle is actually rendered depends on the current render and display modes.

name value description
PMODE 0x00000FFF A bitmask which can be used to check if a particle has any PMODEs set.
PMODE_NONE 0x00000000 Don't draw a point where a particle is at all. Unused.
PMODE_FLAT 0x00000001 Draw a basic pixel, overwriting the color under it. Given by default to everything unless overridden, Doesn't support cola.
PMODE_BLOB 0x00000002 Draw a blob like in blob mode. Everything is given this in blob display mode, but can be set manually.
PMODE_BLUR 0x00000004 Blur effect, used in fancy display mode. Given to all liquids without a graphics functions by default, if not this isn't set.
PMODE_GLOW 0x00000008 Glow effect, used in elements like DEUT and TRON in fancy display mode, also given to radioactive elements.
PMODE_SPARK 0x00000010 Draws a very light sparkle around a particle.
PMODE_FLARE 0x00000020 Draws a flare around a particle, used by BOMB.
PMODE_LFLARE 0x00000040 Very large and bright flare, used by DEST when it hits something.
PMODE_ADD 0x00000080 Like PMODE_FLAT, but adds color to a pixel, instead of overwriting it.
PMODE_BLEND 0x00000100 Basically the same thing as PMODE_ADD, but has better OpenGL support
PSPEC_STICKMAN 0x00000200 Used by stickmen. Won't do anything unless the element actually is a stickman.
OPTIONS 0x0000F000 A bitmask which can be used to check if a particle has any display options set.
NO_DECO 0x00001000 Prevents decoration from being shown on an element.
DECO_FIRE 0x00002000 Allows decoration to be drawn onto the fire effect. All gasses have this on by default.
FIREMODE 0x00FF0000 A bitmask which can be used to check if a particle has any fire graphics set.
FIRE_ADD 0x00010000 Adds a weak fire effect around an element. Does not support many colors like FIRE_BLEND does.
FIRE_BLEND 0x00020000 Adds a strong fire effect around an element. All gasses have this on by default.
FIRE_SPARK 0x00040000 Adds a moderate fire effect around an element. Used by SPRK.
EFFECT 0xFF000000 A bitmask which can be used to check if a particle has any special effects set.
EFFECT_GRAVIN 0x01000000 Adds a PRTI effect. Won't work unless .life and .ctype are set properly in an update function.
EFFECT_GRAVOUT 0x02000000 Adds a PRTO effect. Won't work unless .life and .ctype are set properly in an update function.
EFFECT_LINES 0x04000000 Used by SOAP to draw lines between attached SOAP particles. Ignored by everything else.
EFFECT_DBGLINES 0x08000000 Draw lines between particles of the same type with similar temperatures. Used by WIFI and portals to draw lines between particles of the same channel when in debug mode.

Render modes

These are the values used and returned by ren.renderMode. They are combinations of the above values, and sometimes overlap. All source definitions also include OPTIONS and PSPEC_STICKMAN (so that options can always be set and stickmen are always rendered), but they are not listed here.

name definition in source description
RENDER_EFFE PMODE_SPARK | PMODE_FLARE | PMODE_LFLARE Used in all display modes except for heat, nothing, heat gradient, and life gradient. Turns on all basic effects like flares and portal effects.
RENDER_FIRE PMODE_BLEND | FIREMODE Used in fire, blob, and fancy display modes. Turns on all fire effects.
RENDER_GLOW PMODE_ADD | PMODE_BLEND Used in fancy display mode, so that radioactive elements glow.
RENDER_BLUR PMODE_ADD | PMODE_BLEND Used in fancy display mode, to turn on the liquid blur effect.
RENDER_BLOB PMODE_ADD | PMODE_BLEND causes every particle to get PMODE_BLOB.
RENDER_BASC PMODE_ADD | PMODE_BLEND | EFFECT_LINES Used by every single display mode, turns on PMODE_FLAT so particles get displayed.
RENDER_NONE PMODE_FLAT Not used at all, but would make sure at least each individual pixel gets drawn.

Display modes

These are the values used and returned by ren.displayMode. They can be set together, although no official display mode does this.

name value description
DISPLAY_AIRC 0x00000001 Cracker air display mode, used in alternate velocity display.
DISPLAY_AIRP 0x00000002 Used by pressure display mode.
DISPLAY_AIRV 0x00000004 Used by velocity display mode.
DISPLAY_AIRH 0x00000008 Used by heat display mode.
DISPLAY_AIR 0x0000000F A bitmask which can be used to check if an air display mode is set.
DISPLAY_WARP 0x00000010 Used by fancy display mode, turns on gravity lensing, causing newtonian gravity areas to bend light.
DISPLAY_PERS 0x00000020 Used by persistent display mode.
DISPLAY_EFFE 0x00000040 Doesn't do anything at all, unless maybe OpenGL is on. Unclear what it does even then.

Color modes

These are the values used and returned by ren.colorMode. Only one can be set at a time, and they control which types of colors particles are drawn in.

name description
COLOUR_DEFAULT Default colors, nothing gets changed.
COLOUR_HEAT Render elements in heat display colors. Pink = hottest, Blue = coldest.
COLOUR_LIFE Render elements in a greyscale gradient dependent on .life value.
COLOUR_GRAD Render elements normally, but with a slight greyscale gradient dependent on a particle's temperature.
COLOUR_BASC Remove all color changes from elements, elements get rendered in whichever color their element button is.