Library render

Render library. Screens are 512x512 units. Most functions require that you be in the rendering hook to call, otherwise an error is thrown. +x is right, +y is down

Functions

addBeam( pos, width, textureEnd, color ) Adds a beam control point to the ongoing multi-segment beam rendering operation, if called within a beam generator function.
capturePixels() Dumps the current render target and allows the pixels to be accessed by render.readPixel.
clear( r, g, b, a, clearDepth, clearStencil ) Clears the surface.
clearBuffersObeyStencil( r, g, b, a, clearDepth ) Clears the surface, obeying any stencil checks.
clearDepth() Clears the depth buffer without altering the colour or stencil buffers.
clearStencil() Clears the stencil buffer, resetting every pixel to zero.
clearStencilBufferRectangle( x, y, endX, endY, stencilValue ) Sets the stencil values for a rectangle in screen space to the given value.
computeDynamicLighting( pos, normal ) Computes the dynamic light colour of the surface at the given position and with the given normal.
computeLighting( pos, normal ) Computes the (static) light colour of the surface at the given position and with the given normal.
computeTextureCoords( texture, u, v, endU, endV ) Computes corrected texture co-ordinates for the given texture/material.
createClientModel( model, renderGroup ) Creates an invisible client side model.
createFont( font, size, weight, antialias, additive, shadow, outline, blur ) Creates a font.
cursorPos( ply, screen ) Gets the co-ordinates of where the given player is aiming at on the screen (in screen space).
cutOutStencil() Call this after render.startStencil() to switch to drawing what you want to have the stencil cut out of.
disableScissorRect() Disables the current scissor rect, if one is enabled.
drawBeam( start, end, width, texStart, texEnd, color ) Draws a single-segment beam in 3D space.
drawBox( pos, ang, mins, maxs, color ) Draws a rotated box in 3D space.
drawCircle( x, y, rx, ry, width ) Draws a circle outline.
drawFilledCircle( x, y, rx, ry ) Draws a filled circle.
drawLine( x1, y1, x2, y2, width ) Draws a line in 2D space.
drawLine3D( start, end, color, writeZ ) Draws a line in 3D space.
drawMultiSegmentBeam( numControlPoints, generatorFunc, ... ) Draws a multi-segment beam in 3D space using the given generator function to add beam segments.
drawPoly( polygon ) Draws a polygon.
drawQuad( topLeft, topRight, bottomRight, bottomLeft, color ) Draws a quad in 3D space.
drawQuadFromPlane( pos, normal, width, height, color, rotation ) Draws a quad in 3D space based on the given plane position and normal vector.
drawRawText( text ) Draws the given text using whatever colour was set previously by setColor(), the position set by setTextPos() and the font set by setFont().
drawRect( x, y, w, h ) Draws a rectangle using the current colour.
drawRectOutline( x, y, w, h, thickness ) Draws a rectangle outline using the current colour.
drawRoundedRect( radius, x, y, w, h ) Draws a rounded rectangle using the current colour.
drawSphere( pos, radius, longitudeSteps, latitudeSteps, color ) Draws a sphere in 3D space.
drawSprite( pos, width, height, color ) Draws a sprite in 3D space.
drawStencil() Call this after render.startStencil() to switch to drawing what you want to be contained.
drawText( font, x, y, text, alignment ) Draws the given text using whatever colour was set previously by setColor().
drawTextRotated( text, font, x, y, ang ) Draws the given text using whatever colour was set previously by setColor().
drawTexturedRect( x, y, w, h ) Draws a textured rectangle.
drawTexturedRectRotated( x, y, w, h, rotationDegrees ) Draws a rotated, textured rectangle.
drawTexturedRectUV( x, y, w, h, startU, startV, endU, endV ) Draws a textured rectangle with UV co-ordinates Allowed render contexts: 2D, 3D2D.
drawWireframeBox( pos, ang, mins, maxs, color, writeZ ) Draws a rotated wireframe box in 3D space.
drawWireframeSphere( pos, radius, longitudeSteps, latitudeSteps, color, writeZ ) Draws a wireframe sphere in 3D space.
enableAlpha( shouldWrite ) Sets whether to write alpha when rendering.
enableClipping( enable ) Enables/disables clipping.
enableColor( shouldWrite ) Sets whether to write colour values.
enableDepth( shouldWrite ) Sets whether to write to the depth buffer.
enableScissorRect( x, y, endX, endY ) Enables a scissor rect, which will prevent anything drawing outside the provided bounds.
end3D() Ends a 3D camera.
end3D2D() Ends a 3D2D camera.
endStencil() Ends the stencil operation.
frameNumber() Returns the current frame number.
get3DMaterialFrame() Returns the current frame index of the base texture being rendered by the last set 3D material.
get3DRenderBounds() Returns the minimum and maximum extents within which the current 3D rendering is restricted to, if any.
getAmbientLightColor() Returns the ambient light colour as a vector.
getBlend() Returns the current blend factor (effectively an alpha multiplier) that will be applied to subsequent 3D rendering operations.
getCameraStack() Returns the current camera stack.
getClientModelCount() Returns the number of clientside models you have currently in use across all instances.
getClientModels() Returns a table of all currently active client side models for the current instance.
getColor() Returns the current draw colour's 4 component values.
getColorModulation() Returns the current colour modulation that will be applied to subsequent 3D rendering operations.
getConfiguredScreenRes() Returns the configured size of the Starfall screen.
getIsHighRes() Returns whether the screen is running in high res mode.
getIsWidescreen() Returns whether the screen is running in widescreen mode.
getLightColor( pos ) Returns the light colour at the given position.
getLinearWriteMaterial() Returns a material that can be used to write colour data without gamma correction.
getMatrix() Returns the current render matrix (the resulting matrix from the last pushed matrix after multiplication).
getMaxClientModels() Returns the maximum number of clientside models you can use.
getNum3DMaterialFrames() Returns the number of animated texture frames that are available for the current 3D material's base texture.
getNumTextureFrames() Returns the number of animated texture frames that are available for the current 2D material's base texture.
getScreenInfo() Returns information about the screen, such as dimensions and rotation.
getScreenPos() Returns the screen surface's world position and angle
getScreenRes() Returns the screen resolution in the current rendering context.
getTextSize( font, text ) Gets the size of the given text displayed with the given font in pixels.
getTextureFrame() Returns the current frame index of the base texture being rendered by the last set 2D material.
getTextureID( texture ) Looks up a texture ID by file name.
ignoreZ( ignoreZ ) Sets whether to ignore the depth buffer.
isEmitter() Returns whether the SF instance is an emitter.
isHUD() Returns whether the SF instance is a HUD.
isStencilEnabled() Returns whether a stencil is currently being used.
overrideBlend( enable, sourceBlend, destBlend, blendFunc, sourceBlendAlpha, destBlendAlpha, blendFuncAlpha ) Enables/disables overriding the current blending function.
overrideDepthEnable( enableOverride, shouldWrite ) Allows overriding the default depth write behaviour.
popCustomClipPlane() Pops a clip plane from the clipping plane stack.
popFilterMag() Pops a magnification texture filter from the texture filter stack.
popFilterMin() Pops a minification texture filter from the texture filter stack.
popMatrix() Pops a matrix from the current matrix stack.
pushCustomClipPlane( normal, distance ) Pushes a clip plane onto the clipping plane stack.
pushFilterMag( filterType ) Pushes a magnification texture filter onto the texture filter stack.
pushFilterMin( filterType ) Pushes a minification texture filter onto the texture filter stack.
pushMatrix( mat ) Pushes a matrix onto the matrix stack, pre-multiplying by the previously pushed matrix if present.
readPixel( x, y ) Reads the colour of the specified pixel.
resetModelLighting( r, g, b ) Resets model lighting.
set3DMaterialFrame( frame ) Sets the base texture frame index to use for upcoming render operations using the current 3D material.
setAlphaMultiplier( mult ) Sets a global alpha multiplier on all upcoming 2D drawing operations.
setBlend( a ) Sets the alpha value to draw any models with following this point.
setColor( r, g, b, a ) Sets the draw colour for 2D rendering operations.
setColorModulation( r, g, b ) Sets the colour to draw any models with following this point.
setFont( font ) Sets the font to draw text with.
setLightingMode( mode ) Sets the lighting mode for upcoming model renders.
setLightingOrigin( vec ) Sets the lighting origin.
setLocalModelLights( lights ) Sets up local model lights, you can use up to 4.
setMaterial( mat ) Sets the material for upcoming 3D space rendering operations.
setMaterialOverride( mat ) Sets an override material for upcoming 3D space rendering operations.
setModelLighting( index, r, g, b ) Sets model lighting from one of 6 directions (see the BOX_ enums).
setStencilCompareFunction( stencilComparisonFunction ) Sets the stencil comparison function, which determines which pixels are rendered.
setStencilEnable( enable ) Sets whether stencil testing and writing is enabled or not.
setStencilFailOperation( stencilOperation ) Sets the stencil operation to execute when a stencil test fails for a pixel.
setStencilPassOperation( stencilOperation ) Sets the stencil operation to execute when a stencil test passes for a pixel.
setStencilReferenceValue( value ) Sets the stencil reference value to use when comparing pixel values in the stencil buffer.
setStencilTestMask( value ) Sets the stencil test mask.
setStencilWriteMask( value ) Sets the stencil write mask.
setStencilZFailOperation( stencilOperation ) Sets the stencil operation to execute when a stencil test fails for a pixel due to it being occluded by a previously written pixel in the depth buffer.
setTextPos( x, y ) Sets the position to draw text at.
setTexture( texture ) Sets the texture for upcoming 2D rendering.
setTextureFrame( frame ) Sets the base texture frame index to use for upcoming render operations using the current 2D material.
start3D( pos, ang, fov, x, y, w, h, nearZ, farZ ) Starts a 3D camera context.
start3D2D( pos, ang, scale ) Starts a 3D2D camera.
start3DWithParameters( cameraParameters ) Starts a 3D camera using a parameters table describing the camera.
startStencil() Starts a stencil operation, clearing any previous stencil values.
suppressEngineLighting( suppressEngineLighting ) Sets whether to supress the standard lighting.
toScreen( pos ) Returns the location on the screen of a world space position as a table with x, y and boolean visible values.
vertex( x, y, u, v ) Creates a vertex for use with polygons.

Fields

STUDIO_RENDER This flag is always set when rendering entities, indicating that the entity should render.
STUDIO_VIEWXFORMATTACHMENTS STUDIO_VIEWXFORMATTACHMENTS
STUDIO_DRAWTRANSLUCENTSUBMODELS STUDIO_DRAWTRANSLUCENTSUBMODELS
STUDIO_TWOPASS Indicates that the current render is for an entity that will draw both opaque and translucent renderables (i.e. using RENDERGROUP_BOTH).
STUDIO_STATIC_LIGHTING STUDIO_STATIC_LIGHTING
STUDIO_WIREFRAME STUDIO_WIREFRAME
STUDIO_ITEM_BLINK STUDIO_ITEM_BLINK
STUDIO_NOSHADOWS STUDIO_NOSHADOWS
STUDIO_WIREFRAME_VCOLLIDE STUDIO_WIREFRAME_VCOLLIDE
STUDIO_GENERATE_STATS STUDIO_GENERATE_STATS
STUDIO_SSAODEPTHTEXTURE STUDIO_SSAODEPTHTEXTURE
STUDIO_SHADOWDEPTHTEXTURE STUDIO_SHADOWDEPTHTEXTURE
STUDIO_TRANSPARENCY Indicates that the current render is for the translucent render pass.
RENDERGROUP_BOTH Marks the entity as rendering in both the opaque and translucent passes.
RENDERGROUP_OPAQUE Marks the entity as rendering in just the opaque pass (i.e. the entity is completely opaque).
RENDERGROUP_OPAQUE_BRUSH RENDERGROUP_OPAQUE_BRUSH
RENDERGROUP_OPAQUE_HUGE RENDERGROUP_OPAQUE_HUGE
RENDERGROUP_OTHER RENDERGROUP_OTHER
RENDERGROUP_STATIC RENDERGROUP_STATIC
RENDERGROUP_STATIC_HUGE RENDERGROUP_STATIC_HUGE
RENDERGROUP_TRANSLUCENT Marks the entity as rendering in just the translucent pass (i.e. the entity is completely translucent).
RENDERGROUP_VIEWMODEL RENDERGROUP_VIEWMODEL
RENDERGROUP_VIEWMODEL_TRANSLUCENT RENDERGROUP_VIEWMODEL_TRANSLUCENT
BOX_BACK BOX_BACK
BOX_BOTTOM BOX_BOTTOM
BOX_FRONT BOX_FRONT
BOX_LEFT BOX_LEFT
BOX_RIGHT BOX_RIGHT
BOX_TOP BOX_TOP
MATERIAL_LIGHT_DISABLE Disables the light at the given index.
MATERIAL_LIGHT_POINT A light that emits from a single point in all directions.
MATERIAL_LIGHT_DIRECTIONAL A light that emits from a point in a specific direction.
MATERIAL_LIGHT_SPOT A spotlight comprising of 2 light cones.
TEXT_ALIGN_BOTTOM TEXT_ALIGN_BOTTOM
TEXT_ALIGN_RIGHT TEXT_ALIGN_RIGHT
TEXT_ALIGN_CENTER TEXT_ALIGN_CENTER
TEXT_ALIGN_TOP TEXT_ALIGN_TOP
TEXT_ALIGN_LEFT TEXT_ALIGN_LEFT
CAM_3D2D Constant for a pushed 3D2D camera context.
CAM_3D Constant for a pushed 3D camera context.
TEXFILTER_NONE Disables texture filtering.
TEXFILTER_POINT Applies point texture filtering, making rendering pixelated.
TEXFILTER_LINEAR Applies linear texture filtering, applying a basic linear interpolation to each pixel.
TEXFILTER_ANISOTROPIC Applies anisotropic texture filtering, making textures appear smooth while retaining detail when rendered at an angle.
STENCILOPERATION_KEEP Stencil operation to retain the current stencil value for a pixel.
STENCILOPERATION_ZERO Stencil operation to set the stencil value for a pixel to zero.
STENCILOPERATION_REPLACE Stencil operation to replace the stencil value for a pixel with the current reference value.
STENCILOPERATION_INCRSAT Stencil operation to increment the stencil value for a pixel, stopping at 255.
STENCILOPERATION_DECRSAT Stencil operation to decrement the stencil value for a pixel, stopping at 0.
STENCILOPERATION_INVERT Stencil operation to invert the bits in the stencil value for a pixel.
STENCILOPERATION_INCR Stencil operation to increment the stencil value for a pixel, wrapping back to 0 on overflow.
STENCILOPERATION_DECR Stencil operation to decrement the stencil value for a pixel, wrapping back to 255 on overflow.
STENCILCOMPARISONFUNCTION_NEVER Stencil comparison function that never passes.
STENCILCOMPARISONFUNCTION_LESS Stencil comparison function that passes if the reference value is less than a pixel's value.
STENCILCOMPARISONFUNCTION_EQUAL Stencil comparison function that passes if the reference value is equal to a pixel's value.
STENCILCOMPARISONFUNCTION_LESSEQUAL Stencil comparison function that passes if the reference value is less than or equal to a pixel's value.
STENCILCOMPARISONFUNCTION_GREATER Stencil comparison function that passes if the reference value is greater than a pixel's value.
STENCILCOMPARISONFUNCTION_NOTEQUAL Stencil comparison function that passes if the reference value is not equal to a pixel's value.
STENCILCOMPARISONFUNCTION_GREATEREQUAL Stencil comparison function that passes if the reference value is greater than or equal to a pixel's value.
STENCILCOMPARISONFUNCTION_ALWAYS Stencil comparison function that always passes.
BLEND_ZERO Multiplies the given value by 0.
BLEND_ONE Multiplies the given value by 1.
BLEND_DST_COLOR Multiplies the given value by the colour value that was previously written.
BLEND_ONE_MINUS_DST_COLOR Multiplies the given value by the colour value that was previously written subtracted from 1.
BLEND_SRC_ALPHA Multiplies the given value by the alpha value being written.
BLEND_ONE_MINUS_SRC_ALPHA Multiplies the given value by the alpha value being written subtracted from 1.
BLEND_DST_ALPHA Multiplies the given value by the alpha value that was previously written.
BLEND_ONE_MINUS_DST_ALPHA Multiplies the given value by the alpha value that was previously written subtracted from 1.
BLEND_SRC_ALPHA_SATURATE Multiplies by the minimum of the source alpha, and (1 - destination alpha).
BLEND_SRC_COLOR Multiplies the given value by the colour value that is being written.
BLEND_ONE_MINUS_SRC_COLOR Multiplies the given value by the colour value that is being written subtracted from 1.
BLENDFUNC_ADD Takes the source and destination values, and adds them together (source + destination).
BLENDFUNC_SUBTRACT Subtracts the destination value from the source value (source - destination).
BLENDFUNC_REVERSE_SUBTRACT Subtracts the source value from the destination value (destination - source).


Functions

render.addBeam( pos, width, textureEnd, color )
Adds a beam control point to the ongoing multi-segment beam rendering operation, if called within a beam generator function. Attempting to call this outside of a beam generator function, or to add more control points than were declared will result in an error being thrown.

Environment:

Client

Parameters:

  • (Vector) pos: The position of the control point.
  • (number) width: The width to interpolate to/from on this control point.
  • (number) textureEnd: The texture co-ordinate to apply at this control point.
  • (Color) color: The colour to apply at this control point.
render.capturePixels()
Dumps the current render target and allows the pixels to be accessed by render.readPixel. Allowed render contexts: 2D (render targets only).

Environment:

Client
render.clear( r, g, b, a, clearDepth, clearStencil )
Clears the surface. Only works on screens and inside render target drawing operations.

Environment:

Client

Parameters:

  • (number?) r: Red value to clear to (0-255, default = 0).
  • (number?) g: Green value to clear to (0-255, default = 0).
  • (number?) b: Blue value to clear to (0-255, default = 0).
  • (number?) a: Alpha value to clear to (0-255, default = 255).
  • (boolean?) clearDepth: Whether to clear the depth buffer (default = false).
  • (boolean?) clearStencil: Whether to clear the stencil buffer (default = false).
render.clearBuffersObeyStencil( r, g, b, a, clearDepth )
Clears the surface, obeying any stencil checks. Only works on screens and inside render target drawing operations.

Environment:

Client

Parameters:

  • (number?) r: Red value to clear to (0-255, default = 0).
  • (number?) g: Green value to clear to (0-255, default = 0).
  • (number?) b: Blue value to clear to (0-255, default = 0).
  • (number?) a: Alpha value to clear to (0-255, default = 255).
  • (boolean?) clearDepth: Whether to clear the depth buffer (default = false).
render.clearDepth()
Clears the depth buffer without altering the colour or stencil buffers. Only works on screens and inside render target drawing operations.

Environment:

Client
render.clearStencil()
Clears the stencil buffer, resetting every pixel to zero. Allowed render contexts: all contexts except hologram render callbacks.

Environment:

Client
render.clearStencilBufferRectangle( x, y, endX, endY, stencilValue )
Sets the stencil values for a rectangle in screen space to the given value. Allowed render contexts: 2D (or cameras pushed on top of a 2D context).

Environment:

Client

Parameters:

  • (number) x: The x co-ordinate in screen space of the top-left corner of the rectangle.
  • (number) y: The y co-ordinate in screen space of the top-left corner of the rectangle.
  • (number) endX: The x co-ordinate in screen space of the bottom-right corner of the rectangle.
  • (number) endY: The y co-ordinate in screen space of the bottom-right corner of the rectangle.
  • (number) stencilValue: The new stencil value to set for every matching pixel in the stencil buffer.
render.computeDynamicLighting( pos, normal )
Computes the dynamic light colour of the surface at the given position and with the given normal. This returns a vector with values between 0 and 1 indicating the colour intensity.

Environment:

Client

Parameters:

  • (Vector) pos: The position to compute the lighting at.
  • (Vector) normal: The normal of the surface to compute the lighting for.

Return value:

    (Vector) The dynamic light colour as a vector.
render.computeLighting( pos, normal )
Computes the (static) light colour of the surface at the given position and with the given normal. This returns a vector with values between 0 and 1 indicating the colour intensity.

Environment:

Client

Parameters:

  • (Vector) pos: The position to compute the lighting at.
  • (Vector) normal: The normal of the surface to compute the lighting for.

Return value:

    (Vector) The light colour as a vector.
render.computeTextureCoords( texture, u, v, endU, endV )
Computes corrected texture co-ordinates for the given texture/material. When using drawTexturedRectUV, the engine internally alters the texture co-ordinates. This function accounts for that alteration and ensures the rendering operation uses the intended values.

Environment:

Client

Parameters:

  • texture: The texture ID or IMaterial to compute corrected co-ordinates for.
  • u: The intended u co-ordinate.
  • v: The intended v co-ordinate.
  • endU: The intended end u co-ordinate.
  • endV: The intended end v co-ordinate.

Usage:

    local texture = render.getTextureID( "some/material" ) 
    -- Compute the corrected texture co-ordinates to tile the texture in a 2x2 grid. 
    local u0, v0, u1, v1 = render.computeTextureCoords( texture, 0, 0, 2, 2 ) 
    hook( "render", "example", function() 
    	render.clear() 
    	render.setColor( 255, 255, 255 ) 
    	render.setTexture( texture ) 
    	render.drawTexturedRectUV( 0, 0, 512, 512, u0, v0, u1, v1 ) 
    end )

Return values:

  1. (number) The corrected u co-ordinate.
  2. (number) The corrected v co-ordinate.
  3. (number) The corrected end u co-ordinate.
  4. (number) The corrected end v co-ordinate.
render.createClientModel( model, renderGroup )
Creates an invisible client side model. Call Model:drawModel() to draw it in a 3D camera.

Environment:

Client

Parameters:

  • (string) model: The model path to use.
  • (number?) renderGroup: One of the render.RENDERGROUP_* enums.

Return value:

    (ClientsideModel | nil) The created client side model, or nil if no further models can be created.
render.createFont( font, size, weight, antialias, additive, shadow, outline, blur )
Creates a font. Cannot be used in a rendering hook, use it outside. Returns the font's unique name. This only needs to be called once. After that, use the returned name to reference the font. If using a table of parameters, only the first argument is used. The rest are ignored. Creating a font is a costly process, only create the fonts you absolutely need.

Environment:

Client

Parameters:

  • (Font | string) font: Base font name to use OR a table containing font parameters (see the Font structure).
  • (number?) size: The size of the font in pixels (between 4 and 255, default is 13).
  • (number?) weight: The weight of the font (how thick it is, minimum of 100, default is 500).
  • (boolean?) antialias: Whether to anti-alias the text, which smooths/blurs the edges (default is true).
  • (boolean?) additive: Whether the font should render additively or not (default is false).
  • (boolean?) shadow: Whether to add a shadow to the font (default is false).
  • (boolean?) outline: Whether to add an outline to the font (default is false).
  • (number?) blur: The strength of blurring to apply (between 0 and 10, default is 0).

Return value:

    (string) The name of the font that was created. Use this in later rendering functions.
render.cursorPos( ply, screen )
Gets the co-ordinates of where the given player is aiming at on the screen (in screen space).

Environment:

Client

Parameters:

  • (Player) ply: The player to get the cursor position of.
  • (Entity?) screen: (Optional) Screen entity to get the cursor position for (either a repeater, or another screen).

Return values:

  1. (number | nil) The x co-ordinate of the player's aim position on the screen, or nil if the player's view does not intersect the screen.
  2. (number | nil) The y co-ordinate of the player's aim position on the screen, or nil if the player's view does not intersect the screen.
render.cutOutStencil()
Call this after render.startStencil() to switch to drawing what you want to have the stencil cut out of. This is the opposite of render.drawStencil().

Environment:

Client
render.disableScissorRect()
Disables the current scissor rect, if one is enabled.

Environment:

Client
render.drawBeam( start, end, width, texStart, texEnd, color )
Draws a single-segment beam in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) start: The starting position of the beam.
  • (Vector) end: The ending position of the beam.
  • (number) width: The width of the beam.
  • (number) texStart: The starting texture co-ordinate (between 0 and 1).
  • (number) texEnd: The ending texture co-ordinate (between 0 and 1).
  • (Color) color: The colour of the beam.
render.drawBox( pos, ang, mins, maxs, color )
Draws a rotated box in 3D space. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (Vector) pos: The position of the box.
  • (Angle) ang: The angles of the box.
  • (Vector) mins: The mins vector for the box.
  • (Vector) maxs: The maxs vector for the box.
  • (Color) color: The colour of the box.
render.drawCircle( x, y, rx, ry, width )
Draws a circle outline. For widths > 1, this function can be costly. Consider implementing it yourself with a vertex caching system to get better performance. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: Center x co-ordinate
  • y: Center y co-ordinate
  • rx: X Radius
  • ry: Y Radius
  • width: The width of the outline (default = 1). Widths > 1 are much more costly to draw.
render.drawFilledCircle( x, y, rx, ry )
Draws a filled circle. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: Center x co-ordinate
  • y: Center y co-ordinate
  • rx: X Radius
  • ry: Y Radius
render.drawLine( x1, y1, x2, y2, width )
Draws a line in 2D space. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x1: X start co-ordinate
  • y1: Y start co-ordinate
  • x2: X end co-ordinate
  • y2: Y end co-ordinate
  • width: The width of the line in pixels (default = 1). Widths > 1 are more costly to draw.
render.drawLine3D( start, end, color, writeZ )
Draws a line in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) start: The starting position of the line.
  • (Vector) end: The ending position of the line.
  • (Color) color: The colour of the line.
  • (boolean?) writeZ: (Optional) Whether to render the line using the depth buffer (default = false). This value is always true when rendering in the world (e.g. with an emitter or hologram).
render.drawMultiSegmentBeam( numControlPoints, generatorFunc, ... )
Draws a multi-segment beam in 3D space using the given generator function to add beam segments. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (number) numControlPoints: The number of control points that will be used to draw beam segments (up to 128, n beam segments require n + 1 control points). Exceeding this value will result in an error. At least 2 control points are required to render a beam.
  • (function) generatorFunc: A function that will add beam segments using render.addBeam(). This function cannot yield.
  • (Any...) ...: Arguments to pass to the generator function.

Usage:

    local Ent = ents.self() 
    -- Define a generator function outside the render hook, taking parameters. 
    local function GenerateExampleBeamSegments( Colour ) 
    	-- Inside the generator function, add every declared beam control point. 
    	-- This example draws 3 segments (1 -> 2, 2 -> 3 and 3 -> 4). 
    	render.addBeam( Ent:toWorld( Vector( 0, 0, 0 ) ), 16, 1, Colour ) 
    	render.addBeam( Ent:toWorld( Vector( 0, -32, 0 ) ), 16, 0, Colour ) 
    	render.addBeam( Ent:toWorld( Vector( 0, 0, -32 ) ), 16, 1, Colour ) 
    	render.addBeam( Ent:toWorld( Vector( 0, -32, -32 ) ), 16, 0, Colour ) 
    end 
    -- Pick an appropriate material to render the beam with. 
    local BeamMaterial = Material( "trails/physbeam" ) 
    local White = Color( 255, 255, 255 ) 
    hook( "render", "example", function() 
    	-- Pass the generator function to drawMultiSegmentBeam to render the beam segments. 
    	-- Additional arguments can be passed to the generator to make re-using functions easier. 
    	render.setMaterial( BeamMaterial ) 
    	render.drawMultiSegmentBeam( 4, GenerateExampleBeamSegments, White ) 
    end )
render.drawPoly( polygon )
Draws a polygon. Each vertex must be a table with x, y, u and v fields. Vertices should be in clockwise order, starting at the upper-left most, and form a convex shape. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • (table) polygon: Array of vertices.

Usage:

    -- Draw a triangle in the centre of the screen. 
    render.drawPoly( { 
    	-- Top vertex, u = 0.5 as it's halfway along the width of the shape. 
    	{ x = 256, y = 256 - 64, u = 0.5, v = 0 }, 
    	-- Bottom right vertex. u = 1 as it's the full width along, v = 1 as it's the full height *down*. 
    	{ x = 256 + 64, y = 256 + 64, u = 1, v = 1 }, 
    	-- Bottom left vertex. u = 0 as it's the very left-most point, v = 1 as it's still the bottom. 
    	{ x = 256 - 64, y = 256 + 64, u = 0, v = 1 } 
    } )
render.drawQuad( topLeft, topRight, bottomRight, bottomLeft, color )
Draws a quad in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) topLeft: The top left quad corner.
  • (Vector) topRight: The top right quad corner.
  • (Vector) bottomRight: The bottom right quad corner.
  • (Vector) bottomLeft: The bottom left quad corner.
  • (Color) color: The colour of the quad.
render.drawQuadFromPlane( pos, normal, width, height, color, rotation )
Draws a quad in 3D space based on the given plane position and normal vector. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) pos: The centre position of the quad.
  • (Vector) normal: The normal vector of the quad (pointing upwards).
  • (number) width: The width of the quad.
  • (number) height: The height of the quad.
  • (Color) color: The colour of the quad.
  • (number?) rotation: (Optional) The rotation in degrees to rotate each corner around the normal vector of the quad, relative to the centre position.
render.drawRawText( text )
Draws the given text using whatever colour was set previously by setColor(), the position set by setTextPos() and the font set by setFont(). Unlike drawText, this does not handle alignment, new lines or tabs for you. However, it will be significantly more performant. After drawing, the text position will be updated to be after the width of the drawn text, so you do not need to update it manually unless you wish to render elsewhere. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • text: The text to draw.
render.drawRect( x, y, w, h )
Draws a rectangle using the current colour. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: Top left corner x co-ordinate
  • y: Top left corner y co-ordinate
  • w: Width
  • h: Height
render.drawRectOutline( x, y, w, h, thickness )
Draws a rectangle outline using the current colour. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: Top left corner x co-ordinate
  • y: Top left corner y co-ordinate
  • w: Width
  • h: Height
  • thickness: The thickness of the outline (default = 1). Thicknesses > 1 are slightly more costly to draw.
render.drawRoundedRect( radius, x, y, w, h )
Draws a rounded rectangle using the current colour. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • radius: The radius of the rounded corners. Should be power of 2.
  • x: Top left corner x co-ordinate
  • y: Top left corner y co-ordinate
  • w: Width
  • h: Height
render.drawSphere( pos, radius, longitudeSteps, latitudeSteps, color )
Draws a sphere in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) pos: The position of the sphere.
  • (number) radius: The radius of the sphere.
  • (number) longitudeSteps: The amount of longitude steps (controls how smooth the sphere is).
  • (number) latitudeSteps: The amount of latitude steps (controls how smooth the sphere is).
  • (Color) color: The colour of the sphere.
render.drawSprite( pos, width, height, color )
Draws a sprite in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) pos: The position of the sprite.
  • (number) width: The width of the sprite.
  • (number) height: The height of the sprite.
  • (Color) color: The colour of the sprite.
render.drawStencil()
Call this after render.startStencil() to switch to drawing what you want to be contained.

Environment:

Client
render.drawText( font, x, y, text, alignment )
Draws the given text using whatever colour was set previously by setColor(). This will handle new lines and tabs for you, but will not be as performant as drawRawText(). Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • font: The font name to use.
  • x: X co-ordinate.
  • y: Y co-ordinate.
  • text: Text to draw.
  • alignment: (Optional) Text alignment.
render.drawTextRotated( text, font, x, y, ang )
Draws the given text using whatever colour was set previously by setColor(). The text is rotated around its central point by the given angle. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • text: The text to draw.
  • font: The font to use.
  • x: X co-ordinate.
  • y: Y co-ordinate.
  • ang: Angle in degrees.
render.drawTexturedRect( x, y, w, h )
Draws a textured rectangle. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: X co-ordinate
  • y: Y co-ordinate
  • w: Width
  • h: Height
render.drawTexturedRectRotated( x, y, w, h, rotationDegrees )
Draws a rotated, textured rectangle. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: X co-ordinate of centre of the rectangle (around which it will be rotated)
  • y: Y co-ordinate of centre of the rectangle (around which it will be rotated)
  • w: Width
  • h: Height
  • rotationDegrees: Rotation in degrees
render.drawTexturedRectUV( x, y, w, h, startU, startV, endU, endV )
Draws a textured rectangle with UV co-ordinates Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: X co-ordinate
  • y: Y co-ordinate
  • w: Width
  • h: Height
  • startU: Starting U co-ordinate.
  • startV: Starting V co-ordinate.
  • endU: Ending U co-ordinate.
  • endV: Ending V co-ordinate.
render.drawWireframeBox( pos, ang, mins, maxs, color, writeZ )
Draws a rotated wireframe box in 3D space. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (Vector) pos: The position of the box.
  • (Angle) ang: The angles of the box.
  • (Vector) mins: The mins vector for the box.
  • (Vector) maxs: The maxs vector for the box.
  • (Color) color: The colour of the box.
  • (boolean?) writeZ: (Optional) Whether to render the box using the depth buffer (default = false).
render.drawWireframeSphere( pos, radius, longitudeSteps, latitudeSteps, color, writeZ )
Draws a wireframe sphere in 3D space. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) pos: The position of the sphere.
  • (number) radius: The radius of the sphere.
  • (number) longitudeSteps: The amount of longitude steps (controls how smooth the sphere is).
  • (number) latitudeSteps: The amount of latitude steps (controls how smooth the sphere is).
  • (Color) color: The colour of the sphere.
  • (boolean?) writeZ: (Optional) Whether to render the sphere using the depth buffer (default = false). This value is always true when rendering in the world (e.g. with an emitter or hologram).
render.enableAlpha( shouldWrite )
Sets whether to write alpha when rendering.

Environment:

Client

Parameters:

  • shouldWrite: Whether to write to the alpha channel.
render.enableClipping( enable )
Enables/disables clipping. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (boolean) enable: Sets whether clipping is enabled. You should disable it after.
render.enableColor( shouldWrite )
Sets whether to write colour values. Use this to render to the stencil/depth buffer without it being visible. NOTE: The engine does not render in 2D if the current colour's alpha is 0, even if colour writing is disabled. You must have a non-zero alpha value set to render to the stencil/depth buffer.

Environment:

Client

Parameters:

  • shouldWrite: Whether to write colour values or not.

Usage:

    render.startStencil() 
    -- Turn off writing colour values. 
    render.enableColor( false ) 
    -- Render your bounds here 
    -- Turn back on writing colour values. 
    render.enableColor( true ) 
    render.drawStencil() 
    -- Draw things constrained to the stencil 
    render.endStencil()
render.enableDepth( shouldWrite )
Sets whether to write to the depth buffer. Note that "enabling" depth writing here defers to the current rendering context's depth writing mode, which may not actually be enabled. Use render.overrideDepthEnable() to force depth writing.

Environment:

Client

Parameters:

  • shouldWrite: Whether to write to the depth buffer.
render.enableScissorRect( x, y, endX, endY )
Enables a scissor rect, which will prevent anything drawing outside the provided bounds. If a render matrix has been previously pushed, it will be applied to the given co-ordinate values to produce a screen-space scissor rectangle. Note that scissor rectanges are axis-aligned, and thus only translation and scaling make sense. For more complex use cases, see render.startStencil()/render.drawStencil()/render.cutOutStencil(). Allowed render contexts: 2D (or cameras pushed on top of a 2D context).

Environment:

Client

Parameters:

  • x: The x co-ordinate of the rect's top-left corner.
  • y: The y co-ordinate of the rect's top-left corner.
  • endX: The x co-ordinate of the rect's bottom-right corner.
  • endY: The y co-ordinate of the rect's bottom-right corner.

Return values:

  1. (number) The screen-space x co-ordinate of the rect's top-left corner, after applying the current render matrix.
  2. (number) The screen-space y co-ordinate of the rect's top-left corner, after applying the current render matrix.
  3. (number) The screen-space x co-ordinate of the rect's bottom-right corner, after applying the current render matrix.
  4. (number) The screen-space y co-ordinate of the rect's bottom-right corner, after applying the current render matrix.
render.end3D()
Ends a 3D camera. You must do this to start a new one, and you should end every camera you start.

Environment:

Client
render.end3D2D()
Ends a 3D2D camera. You must do this in order to start a new one, and you should end every camera you start.

Environment:

Client
render.endStencil()
Ends the stencil operation. Call this after drawStencil() to stop restricting drawing operations.

Environment:

Client
render.frameNumber()
Returns the current frame number.

Environment:

Client
render.get3DMaterialFrame()
Returns the current frame index of the base texture being rendered by the last set 3D material.

Environment:

Client
render.get3DRenderBounds()
Returns the minimum and maximum extents within which the current 3D rendering is restricted to, if any. Rendering is restricted when drawing in the world, such as in an emitter's render hook or a hologram render callback.

Environment:

Client

Return values:

  1. (number) The x co-ordinate of the minimum corner of the render bounds.
  2. (number) The y co-ordinate of the minimum corner of the render bounds.
  3. (number) The z co-ordinate of the minimum corner of the render bounds.
  4. (number) The x co-ordinate of the maximum corner of the render bounds.
  5. (number) The y co-ordinate of the maximum corner of the render bounds.
  6. (number) The z co-ordinate of the maximum corner of the render bounds.
render.getAmbientLightColor()
Returns the ambient light colour as a vector.

Environment:

Client
render.getBlend()
Returns the current blend factor (effectively an alpha multiplier) that will be applied to subsequent 3D rendering operations. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Return value:

    (number) Alpha value between 0 and 1.
render.getCameraStack()
Returns the current camera stack. Each element is one of the render.CAM_* constants indicating the type of camera that was pushed. The most recently pushed camera is at the end of the array.

Environment:

Client

Return value:

    (table) The current camera stack as an array.
render.getClientModelCount()
Returns the number of clientside models you have currently in use across all instances.

Environment:

Client
render.getClientModels()
Returns a table of all currently active client side models for the current instance.

Environment:

Client
render.getColor()
Returns the current draw colour's 4 component values.

Environment:

Client

Return values:

  1. (number) The current red value (between 0 and 255).
  2. (number) The current green value (between 0 and 255).
  3. (number) The current blue value (between 0 and 255).
  4. (number) The current alpha value (between 0 and 255).
render.getColorModulation()
Returns the current colour modulation that will be applied to subsequent 3D rendering operations. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Return values:

  1. (number) Red modulation (between 0 and 1)
  2. (number) Green modulation (between 0 and 1)
  3. (number) Blue modulation (between 0 and 1)
render.getConfiguredScreenRes()
Returns the configured size of the Starfall screen. Use render.getScreenRes() to get the resolution of the current rendering context.

Environment:

Client

Return values:

  1. (number) The configured width of the screen in pixels.
  2. (number) The configured height of the screen in pixels.
render.getIsHighRes()
Returns whether the screen is running in high res mode.

Deprecated: Use render.getConfiguredScreenRes().

Environment:

Client
render.getIsWidescreen()
Returns whether the screen is running in widescreen mode.

Deprecated: Use render.getConfiguredScreenRes().

Environment:

Client
render.getLightColor( pos )
Returns the light colour at the given position.

Environment:

Client

Parameters:

  • (Vector) pos: The position to get the light colour for.
render.getLinearWriteMaterial()
Returns a material that can be used to write colour data without gamma correction. This is intended to be used within render targets to write exact colour data.

Environment:

Client
render.getMatrix()
Returns the current render matrix (the resulting matrix from the last pushed matrix after multiplication).

Environment:

Client
render.getMaxClientModels()
Returns the maximum number of clientside models you can use.

Environment:

Client
render.getNum3DMaterialFrames()
Returns the number of animated texture frames that are available for the current 3D material's base texture.

Environment:

Client
render.getNumTextureFrames()
Returns the number of animated texture frames that are available for the current 2D material's base texture.

Environment:

Client
render.getScreenInfo()
Returns information about the screen, such as dimensions and rotation. Note: this does a table copy so move it out of your draw hook.

Deprecated: Use screen.getParameters() which returns a more usable format.

Environment:

Client

Return value:

    (ScreenInfo) A table describing the screen.
render.getScreenPos()
Returns the screen surface's world position and angle

Environment:

Client

Return values:

  1. (Vector) The screen position
  2. (Angle) The screen angle
render.getScreenRes()
Returns the screen resolution in the current rendering context. For HUDs/emitters, this returns the local player's screen resolution. For screens or inside render targets, when called during rendering this returns the size of the render target. To get the configured resolution of a Starfall screen, use render.getConfiguredScreenRes().

Environment:

Client

Return values:

  1. (number) Width of the current rendering context in pixels.
  2. (number) Height of the current rendering context in pixels.
render.getTextSize( font, text )
Gets the size of the given text displayed with the given font in pixels.

Environment:

Client

Parameters:

  • font: Font name returned by createFont
  • text: Text string to check the size of

Return values:

  1. (number) Width of the text.
  2. (number) Height of the text.
render.getTextureFrame()
Returns the current frame index of the base texture being rendered by the last set 2D material.

Environment:

Client
render.getTextureID( texture )
Looks up a texture ID by file name. The returned ID can be passed to render.setTexture(). When passed a PNG file path, the resulting material is equivalent to Material( texture, "noclamp" ). For other materials, the returned ID will correspond to a material that can be used in a 2D rendering context using the "UnlitGeneric" shader. For materials that already use the "UnlitGeneric" shader, use the Material() constructor instead of this function to preserve the original material parameters.

Environment:

Client

Parameters:

  • (string) texture: Texture file path.

Return value:

    (number) The ID of the texture, or nil if no such texture exists.
render.ignoreZ( ignoreZ )
Sets whether to ignore the depth buffer. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (boolean) ignoreZ: Whether to ignore depth.
render.isEmitter()
Returns whether the SF instance is an emitter.

Environment:

Client
render.isHUD()
Returns whether the SF instance is a HUD.

Environment:

Client
render.isStencilEnabled()
Returns whether a stencil is currently being used.

Environment:

Client

Return value:

    (boolean) True if a stencil is currently in use, false otherwise.
render.overrideBlend( enable, sourceBlend, destBlend, blendFunc, sourceBlendAlpha, destBlendAlpha, blendFuncAlpha )
Enables/disables overriding the current blending function.

Environment:

Client

Parameters:

  • enable: Whether to enable the override.
  • sourceBlend: The blending factor for the source colour values (one of render.BLEND_*).
  • destBlend: The blending factor for the destination colour values (one of render.BLEND_*).
  • blendFunc: The blending function to use for colour (one of render.BLENDFUNC_*).
  • sourceBlendAlpha: The blending factor for the source alpha value (one of render.BLEND_*).
  • destBlendAlpha: The blending factor for the destination alpha value (one of render.BLEND_*).
  • blendFuncAlpha: The blending function to use for alpha (one of render.BLENDFUNC_*).
render.overrideDepthEnable( enableOverride, shouldWrite )
Allows overriding the default depth write behaviour. This can be used to make opaque rendered elements in 3D2D properly occlude each other.

Environment:

Client

Parameters:

  • enableOverride: Whether to override depth writing behaviour.
  • shouldWrite: Whether depth writing should be enabled. Has no effect if the override is not enabled.

Usage:

    -- Force depth writing to be enabled (must be done outside the 3D2D block). 
    render.overrideDepthEnable( true, true ) 
     
    -- First render a red rectangle. 
    render.start3D2D( Pos, Ang, 0.1 ) 
        render.setColor( 255, 0, 0 ) 
        render.drawRect( 0, 0, 256, 256 ) 
    render.end3D2D() 
     
    -- Then render a yellow rectange behind it, note how this rectangle is occluded. 
    -- If you comment out the overrideDepthEnable above, this will draw over the top of the red rectangle. 
    render.start3D2D( Pos - Dir * 5, Ang, 0.1 ) 
        render.setColor( 255, 255, 0 ) 
        render.drawRect( 0, 0, 256, 256 ) 
    render.end3D2D() 
     
    -- Stop overriding depth writing. 
    render.overrideDepthEnable( false )
render.popCustomClipPlane()
Pops a clip plane from the clipping plane stack. Allowed render contexts: 3D camera.

Environment:

Client
render.popFilterMag()
Pops a magnification texture filter from the texture filter stack.

Environment:

Client
render.popFilterMin()
Pops a minification texture filter from the texture filter stack.

Environment:

Client
render.popMatrix()
Pops a matrix from the current matrix stack. Note that 3D2D cameras have their own separate matrix stack, thus attempting to pop a matrix pushed before starting a 3D2D camera will result in an error, and any matrices not popped at the end of a 3D2D camera will be popped automatically.

Environment:

Client
render.pushCustomClipPlane( normal, distance )
Pushes a clip plane onto the clipping plane stack. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (Vector) normal: The normal vector of the plane.
  • (number) distance: The distance of the plane from the origin along the given normal vector.
render.pushFilterMag( filterType )
Pushes a magnification texture filter onto the texture filter stack. This applies when a texture is being rendered at a larger size than the texture itself.

Environment:

Client

Parameters:

  • (number?) filterType: (Optional) The filter to apply (one of render.TEXFILTER_*, default = render.TEXFILTER_ANISOTROPIC).
render.pushFilterMin( filterType )
Pushes a minification texture filter onto the texture filter stack. This applies when a texture is being rendered at a smaller size than the texture itself.

Environment:

Client

Parameters:

  • (number?) filterType: (Optional) The filter to apply (one of render.TEXFILTER_*, default = render.TEXFILTER_ANISOTROPIC).
render.pushMatrix( mat )
Pushes a matrix onto the matrix stack, pre-multiplying by the previously pushed matrix if present. Note that 3D2D cameras have their own separate matrix stack, thus attempting to pop a matrix pushed before starting a 3D2D camera will result in an error, and any matrices not popped at the end of a 3D2D camera will be popped automatically.

Environment:

Client

Parameters:

  • mat: The matrix
render.readPixel( x, y )
Reads the colour of the specified pixel. Allowed render contexts: 2D (render targets only).

Environment:

Client

Parameters:

  • x: Pixel x co-ordinate.
  • y: Pixel y co-ordinate.

Return value:

    (Color) Colour of the pixel as a colour object.
render.resetModelLighting( r, g, b )
Resets model lighting. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (number?) r: The red colour value to use (between 0 and 1, default = 1).
  • (number?) g: The green colour value to use (between 0 and 1, default = 1).
  • (number?) b: The blue colour value to use (between 0 and 1, default = 1).
render.set3DMaterialFrame( frame )
Sets the base texture frame index to use for upcoming render operations using the current 3D material.

Environment:

Client

Parameters:

  • (number) frame: The 0-based frame index to use (cannot exceed render.getNum3DMaterialFrames()).
render.setAlphaMultiplier( mult )
Sets a global alpha multiplier on all upcoming 2D drawing operations.

Environment:

Client

Parameters:

  • mult: Value between 0 and 1 to multiply alpha by.
render.setBlend( a )
Sets the alpha value to draw any models with following this point. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • a: Alpha value between 0 and 1.
render.setColor( r, g, b, a )
Sets the draw colour for 2D rendering operations.

Environment:

Client

Parameters:

  • (number | Color?) r: Red value or a colour object.
  • (number?) g: Green value
  • (number?) b: Blue value
  • (number?) a: Alpha value
render.setColorModulation( r, g, b )
Sets the colour to draw any models with following this point. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • r: Red value between 0 and 1.
  • g: Green value between 0 and 1.
  • b: Blue value between 0 and 1.
render.setFont( font )
Sets the font to draw text with. Use before drawRawText() to set its font.

Environment:

Client

Parameters:

  • font: The font name to use.
render.setLightingMode( mode )
Sets the lighting mode for upcoming model renders. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (number) mode: 0 is default, 1 is shaded, 2 is fullbright.
render.setLightingOrigin( vec )
Sets the lighting origin. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (Vector) vec: The new lighting origin.
render.setLocalModelLights( lights )
Sets up local model lights, you can use up to 4. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (table | nil) lights: A table of up to 4 lights (see the LocalLight structure). Pass nil to reset them.
render.setMaterial( mat )
Sets the material for upcoming 3D space rendering operations.

Environment:

Client

Parameters:

  • (IMaterial | RenderTarget | nil) mat: The material to use, or nil to set to the default material.
render.setMaterialOverride( mat )
Sets an override material for upcoming 3D space rendering operations. This can be used to override the material on clientside models and holograms.

Environment:

Client

Parameters:

  • (IMaterial | RenderTarget | nil) mat: The material to use, or nil to remove any override material.
render.setModelLighting( index, r, g, b )
Sets model lighting from one of 6 directions (see the BOX_ enums). Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (number) index: Which direction light to set (BOX_ enums).
  • (number?) r: The red colour value to use (between 0 and 1, default = 1).
  • (number?) g: The green colour value to use (between 0 and 1, default = 1).
  • (number?) b: The blue colour value to use (between 0 and 1, default = 1).
render.setStencilCompareFunction( stencilComparisonFunction )
Sets the stencil comparison function, which determines which pixels are rendered.

Environment:

Client

Parameters:

  • (number) stencilComparisonFunction: The comparison function to use (one of render.STENCILCOMPARISONFUNCTION_*).
render.setStencilEnable( enable )
Sets whether stencil testing and writing is enabled or not. This is a lower-level interface into the stencil buffer. For most stencil use cases, use render.startStencil() instead. Allowed render contexts: all contexts except hologram render callbacks.

Environment:

Client

Parameters:

  • (boolean) enable: Whether to enable stencil testing and writing.
render.setStencilFailOperation( stencilOperation )
Sets the stencil operation to execute when a stencil test fails for a pixel.

Environment:

Client

Parameters:

  • (number) stencilOperation: The operation to use (one of render.STENCILOPERATION_*).
render.setStencilPassOperation( stencilOperation )
Sets the stencil operation to execute when a stencil test passes for a pixel.

Environment:

Client

Parameters:

  • (number) stencilOperation: The operation to use (one of render.STENCILOPERATION_*).
render.setStencilReferenceValue( value )
Sets the stencil reference value to use when comparing pixel values in the stencil buffer.

Environment:

Client

Parameters:

  • (number) value: The reference value (between 0 and 255).
render.setStencilTestMask( value )
Sets the stencil test mask. All stencil values read from the stencil buffer will be combined with this mask using a bitwise-and operation before they are used in comparison functions.

Environment:

Client

Parameters:

  • (number) value: The mask to set (a single byte, 0-255). Setting to 255 disables masking.
render.setStencilWriteMask( value )
Sets the stencil write mask. All stencil values written to the stencil buffer will be combined with this mask using a bitwise-and operation before they are committed.

Environment:

Client

Parameters:

  • (number) value: The mask to set (a single byte, 0-255). Setting to 255 disables masking.
render.setStencilZFailOperation( stencilOperation )
Sets the stencil operation to execute when a stencil test fails for a pixel due to it being occluded by a previously written pixel in the depth buffer.

Environment:

Client

Parameters:

  • (number) stencilOperation: The operation to use (one of render.STENCILOPERATION_*).
render.setTextPos( x, y )
Sets the position to draw text at. Use before calling drawRawText() to set its position. Allowed render contexts: 2D, 3D2D.

Environment:

Client

Parameters:

  • x: X co-ordinate.
  • y: Y co-ordinate.
render.setTexture( texture )
Sets the texture for upcoming 2D rendering.

Environment:

Client

Parameters:

  • (number | IMaterial | RenderTarget | nil) texture: Either a texture ID, an IMaterial, a render target using the UnlitGenric shader, or nil to reset the texture.
render.setTextureFrame( frame )
Sets the base texture frame index to use for upcoming render operations using the current 2D material.

Environment:

Client

Parameters:

  • (number) frame: The 0-based frame index to use (cannot exceed render.getNumTextureFrames()).
render.start3D( pos, ang, fov, x, y, w, h, nearZ, farZ )
Starts a 3D camera context. Used to render 3D models on a 2D surface. Calling with no arguments will replicate the current player's view. See render.start3DWithParameters for a more advanced version of this function that can handle orthographic projections.

Environment:

Client

Parameters:

  • (Vector?) pos: The position in the new 3D world to position the camera.
  • (Angle?) ang: The angles of the camera.
  • (number?) fov: The field of view of the camera.
  • (number?) x: The X position on the 2D surface to draw the 3D world.
  • (number?) y: The Y position on the 2D surface to draw the 3D world.
  • (number?) w: The width to take up on the 2D surface.
  • (number?) h: The height to take up on the 2D surface.
  • (number?) nearZ: The distance from the camera to start the near clipping plane.
  • (number?) farZ: The distance from the camera to start the far clipping plane.
render.start3D2D( pos, ang, scale )
Starts a 3D2D camera. Rendering inside this will be drawn in the world at the given location. Allowed render contexts: 3D camera, 3D world (emitter/holograms).

Environment:

Client

Parameters:

  • (Vector) pos: Position of the top left corner of the 3D2D camera.
  • (Angles) ang: Angles of the 3D2D camera.
  • (number) scale: Scale multiplier to apply to all rendering within the camera.
render.start3DWithParameters( cameraParameters )
Starts a 3D camera using a parameters table describing the camera. This can be used for more advanced 3D rendering, such as orthographic projections.

Environment:

Client

Parameters:

  • (CameraParameters3D) cameraParameters: The parameters that describe the camera to start.
render.startStencil()
Starts a stencil operation, clearing any previous stencil values. Anything drawn after this and before calling render.drawStencil() will be used to restrict drawing. Anything drawn after this and before calling render.cutOutStencil() will be cut out of what's drawn after. For simple 2D box clipping, consider using render.enableScissorRect() instead. Allowed render contexts: all contexts except hologram render callbacks.

Environment:

Client

Usage:

    -- Start the stencil, and draw a box to contain our content. 
    render.startStencil() 
    render.setColor( 255, 255, 255 ) 
    render.drawRect( 128, 128, 256, 256 ) 
    -- Now draw text inside the box. 
    render.drawStencil() 
    render.setColor( 0, 0, 0 ) 
    render.drawText( Font, 256, 256, "Hello World!", render.TEXT_ALIGN_CENTER ) 
    -- Finally, end the stencil. 
    render.endStencil()
render.suppressEngineLighting( suppressEngineLighting )
Sets whether to supress the standard lighting. Allowed render contexts: 3D camera.

Environment:

Client

Parameters:

  • (boolean) suppressEngineLighting: Whether to suppress the standard lighting.
render.toScreen( pos )
Returns the location on the screen of a world space position as a table with x, y and boolean visible values. This only works on HUDs.

Deprecated: Use Vector:ToScreen() to get the same result.

Environment:

Client

Parameters:

  • pos: World-space position vector you want to know the onscreen location of.
render.vertex( x, y, u, v )
Creates a vertex for use with polygons. This just creates a table; it doesn't really do anything special

Deprecated: This is literally creating a table. You don't need to use it.

Environment:

Client

Parameters:

  • x:
  • y:
  • u:
  • v:

Return value:

    (Vertex) { x = x or 0, y = y or 0, u = u or 0, v = v or 0 }

Valid XHTML 1.0!