Render Reference - Beams

<cat>Dev</cat>
<title>Render Reference - Beams</title>

# Render Library References
These pages seek to provide helpful insight into the groups of functions provided by the <page text="Render Library">render</page>.

The major function groups are:
* **Beams**
* <page text="Minification and Magnification Texture Filters">render_min_mag_filters</page>
* <page text="Render Targets">render_rendertargets</page>
	* <page text="Stencils">render_stencils</page>

# What are Beams?
The Beam functions make it easy to draw continuous lines in 3D space out of multiple connected Beam Segments.  
Beam Segments are drawn out of textured quads that rotate to try to always face the camera (Billboards) in order to hide their flatness.  They're used for things like the flame on thrusters, ropes, lightning effects, and more.

There are two approaches for drawing Beams:
* Straight-line Beams that only require a single Beam Segment can be easily drawn using: 
  * <page text="render.DrawBeam()">render.DrawBeam</page>  
* Continuous Beams that bend, curve, or otherwise require multiple  Beam Segments can be drawn using:
  * <page text="render.StartBeam()">render.StartBeam</page>
  * <page text="render.AddBeam()">render.AddBeam</page>
  * <page text="render.EndBeam()">render.EndBeam</page>

# Examples
<example name="Multi-Segment">
	<description>
		Drawing a star using a continuous Beam made out of multiple Beam Segments.

		If you would like to run this example yourself, create a new folder in `garrysmod/addons` called "RenderBeamExample" and place the sample code below into a `.lua` file in `garrysmod/addons/RenderBeamExample/lua/autorun/client/`

		Ensure that any other example code is removed or replaced to prevent unexpected behavior!
	</description>
	<code>
-- Configuration variables
local beamWidth = 10
local starRadius = 100
local starCenter = Vector( 0, 0, 0 )

-- Calculate the points of the star
-- These angles were determined by guessing and checking until it looked good
local starTopLeft =     starCenter + Vector( 0, math.sin( math.rad(      -60 ) ), math.cos( math.rad(      -60 ) ) ) * starRadius
local starTopRight =    starCenter + Vector( 0, math.sin( math.rad(       60 ) ), math.cos( math.rad(       60 ) ) ) * starRadius
local starTopCenter =   starCenter + Vector( 0, math.sin( math.rad(        0 ) ), math.cos( math.rad(        0 ) ) ) * starRadius
local starBottomLeft =  starCenter + Vector( 0, math.sin( math.rad( 180 + 35 ) ), math.cos( math.rad( 180 + 35 ) ) ) * starRadius
local starBottomRight = starCenter + Vector( 0, math.sin( math.rad( 180 - 35 ) ), math.cos( math.rad( 180 - 35 ) ) ) * starRadius

hook.Add( "PostDrawOpaqueRenderables", "RenderBeamMultiSegmentExample", function()
    -- Use a material that responds to the Beam's color
    render.SetColorMaterial()

    -- Uncomment the line below to see a wireframe view of the Beam Segments
    -- render.SetMaterial( Material( "models/wireframe" ) )

    -- Each render.AddBeam() call adds another "stop" along the Beam's path.
    -- There must be at least two "stops" in order for a Beam Segment to be drawn between them.
    render.StartBeam( 6 )
        render.AddBeam( starBottomLeft,  beamWidth, 0, Color( 162, 224,  46 ) )
        render.AddBeam( starTopCenter,   beamWidth, 0, Color(  27, 189, 189 ) )
        render.AddBeam( starBottomRight, beamWidth, 0, Color( 190,  38, 165 ) )
        render.AddBeam( starTopLeft,     beamWidth, 0, Color( 224, 132,  46 ) )
        render.AddBeam( starTopRight,    beamWidth, 0, Color( 207,  30,  30 ) )
        render.AddBeam( starBottomLeft,  beamWidth, 0, Color( 162, 224,  46 ) )
    render.EndBeam()
end )
	</code>
</example>

Notice that where the Beam starts and ends (The bottom-left corner of the star) the Beam is the width specified in the calls to <page>render.AddBeam</page>.  In the other corners of the star, the Beam appears thinner due to the end of the Beam being rotated to accomodate the next Beam Segment's direction.  This is more easily seen in the wireframe view seen in the second screenshot below.
<upload src="b2b4c/8dc2b2b7a9594a3.png" size="1145720" name="MultiSegmentBeamStarColor.png" />
<upload src="b2b4c/8dc2b2b7d90346b.png" size="1043051" name="MultiSegmentBeamStarWireframe.png" />


<example name="Single-Segment">
	<description>
		Drawing a star using several Beams made out of single Beam Segments.

		If you would like to run this example yourself, create a new folder in `garrysmod/addons` called "RenderBeamExample" and place the sample code below into a `.lua` file in `garrysmod/addons/RenderBeamExample/lua/autorun/client/`

		Ensure that any other example code is removed or replaced to prevent unexpected behavior!
	</description>
	<code>
-- Configuration variables
local beamWidth = 10
local starRadius = 100
local starCenter = Vector( 0, 0, 0 )

-- Calculate the points of the star
-- These angles were determined by guessing and checking until it looked good
local starTopLeft =     starCenter + Vector( 0, math.sin( math.rad(      -60 ) ), math.cos( math.rad(      -60 ) ) ) * starRadius
local starTopRight =    starCenter + Vector( 0, math.sin( math.rad(       60 ) ), math.cos( math.rad(       60 ) ) ) * starRadius
local starTopCenter =   starCenter + Vector( 0, math.sin( math.rad(        0 ) ), math.cos( math.rad(        0 ) ) ) * starRadius
local starBottomLeft =  starCenter + Vector( 0, math.sin( math.rad( 180 + 35 ) ), math.cos( math.rad( 180 + 35 ) ) ) * starRadius
local starBottomRight = starCenter + Vector( 0, math.sin( math.rad( 180 - 35 ) ), math.cos( math.rad( 180 - 35 ) ) ) * starRadius

hook.Add( "PostDrawOpaqueRenderables", "RenderBeamSingleSegmentExample", function()
    -- Use a material that responds to the beam's color
    render.SetColorMaterial()

    -- Uncomment this line to see a wireframe view of the beams
    -- render.SetMaterial( Material( "models/wireframe" ) )

    -- Draw the lines of the star between the calculated points
    render.DrawBeam( starBottomLeft,  starTopCenter,   beamWidth, 0, 1, Color( 162, 224,  46 ) )
    render.DrawBeam( starTopCenter,   starBottomRight, beamWidth, 0, 1, Color(  27, 189, 189 ) )
    render.DrawBeam( starBottomRight, starTopLeft,     beamWidth, 0, 1, Color( 190,  38, 165 ) )
    render.DrawBeam( starTopLeft,     starTopRight,    beamWidth, 0, 1, Color( 224, 132,  46 ) )
    render.DrawBeam( starTopRight,    starBottomLeft,  beamWidth, 0, 1, Color( 207,  30,  30 ) )
end )
	</code>
</example>

<upload src="b2b4c/8dc2cc787b18ab9.png" size="1808082" name="SingleSegmentBeamStarColor.png" />
<upload src="b2b4c/8dc2cc6fcb4bb0b.png" size="2061479" name="SingleSegmentBeamStarWireframe.png" />

Render Reference - Beams

Account Management

Special Pages

Wiki List

Garry's Mod Wiki