Lua API:Renderer

From The Powder Toy
Revision as of 23:15, 14 March 2014 by jacob1 (talk | contribs) (Update constants section with info on particle display modes)
Jump to: navigation, search

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)

If called with no arguments, returns the current colour mode. If an argument is passed in, sets the colour mode. Available settings are:

COLOUR_BASC
COLOUR_HEAT
COLOUR_GRAD
COLOUR_LIFE
COLOUR_DEFAULT 

renderer.colorMode

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

An alias for ren.colourMode.

renderer.decorations

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

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.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.

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
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 stronger fire effect around an element. All gasses have this on by default.
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.

COLOUR

COLOUR_BASC
COLOUR_HEAT
COLOUR_GRAD
COLOUR_LIFE
COLOUR_DEFAULT

DISPLAY

DISPLAY_PERS
DISPLAY_WARP
DISPLAY_AIRH
DISPLAY_AIRV
DISPLAY_EFFE
DISPLAY_AIRC
DISPLAY_AIR
DISPLAY_AIRP

RENDER

RENDER_EFFE
RENDER_BLUR
RENDER_GLOW
RENDER_NONE
RENDER_FIRE
RENDER_BASC
RENDER_BLOB