Difference between revisions of "love.graphics.clear"

(Add example)
(Updated for 11.0)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
Clears the screen to the [[love.graphics.setBackgroundColor|background color]] in LÖVE 0.9.2 and earlier, or to the specified color in [[0.10.0]] and newer.
+
Clears the screen or active [[Canvas]] to the specified color.
  
 
This function is called automatically before [[love.draw]] in the default [[love.run]] function. See the example in [[love.run]] for a typical use of this function.
 
This function is called automatically before [[love.draw]] in the default [[love.run]] function. See the example in [[love.run]] for a typical use of this function.
Line 5: Line 5:
 
Note that the [[love.graphics.setScissor|scissor area]] bounds the cleared region.
 
Note that the [[love.graphics.setScissor|scissor area]] bounds the cleared region.
  
 +
In versions prior to [[11.0]], color component values were within the range of 0 to 255 instead of 0 to 1.
 +
 +
In versions prior to [[0.10.0]], this function clears the screen to the currently set [[love.graphics.setBackgroundColor|background color]] instead.
 
== Function ==
 
== Function ==
 
Clears the screen to the background color in 0.9.2 and earlier, or to transparent black (0, 0, 0, 0) in LÖVE [[0.10.0]] and newer.
 
Clears the screen to the background color in 0.9.2 and earlier, or to transparent black (0, 0, 0, 0) in LÖVE [[0.10.0]] and newer.
Line 21: Line 24:
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.graphics.clear( r, g, b, a )
+
love.graphics.clear( r, g, b, a, clearstencil, cleardepth )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
Line 27: Line 30:
 
{{param|number|g|The green channel of the color to clear the screen to.}}
 
{{param|number|g|The green channel of the color to clear the screen to.}}
 
{{param|number|b|The blue channel of the color to clear the screen to.}}
 
{{param|number|b|The blue channel of the color to clear the screen to.}}
−
{{param|number|a (255)|The alpha channel of the color to clear the screen to.}}
+
{{param|number|a (1)|The alpha channel of the color to clear the screen to.}}
 +
{{New feature|11.0|
 +
{{param|boolean|clearstencil (true)|Whether to clear the active stencil buffer, [[love.graphics.setCanvas|if present]]. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.}}
 +
{{param|boolean|cleardepth (true)|Whether to clear the active depth buffer, [[love.graphics.setCanvas|if present]]. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.}}
 +
}}
  
 
=== Returns ===
 
=== Returns ===
Line 37: Line 44:
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.graphics.clear( color, ... )
+
love.graphics.clear( color, ..., clearstencil, cleardepth )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
 
{{param|table|color|A table in the form of <code>{r, g, b, a}</code> containing the color to clear the first active Canvas to.}}
 
{{param|table|color|A table in the form of <code>{r, g, b, a}</code> containing the color to clear the first active Canvas to.}}
 
{{param|table|...|Additional tables for each active Canvas.}}
 
{{param|table|...|Additional tables for each active Canvas.}}
 +
{{New feature|11.0|
 +
{{param|boolean|clearstencil (true)|Whether to clear the active stencil buffer, [[love.graphics.setCanvas|if present]]. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.}}
 +
{{param|boolean|cleardepth (true)|Whether to clear the active depth buffer, [[love.graphics.setCanvas|if present]]. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.}}
 +
}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
 
=== Notes ===
 
=== Notes ===
 
A color must be specified for each active Canvas, when this function variant is used.
 
A color must be specified for each active Canvas, when this function variant is used.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
Clears the stencil or depth buffers without having to clear the color canvas as well.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.clear( clearcolor, clearstencil, cleardepth )
 +
</source>
 +
=== Arguments ===
 +
{{param|boolean|clearcolor|Whether to clear the active color canvas to transparent black (<code>0, 0, 0, 0</code>). Typically this should be set to false with this variant of the function.}}
 +
{{param|boolean|clearstencil|Whether to clear the active stencil buffer, [[love.graphics.setCanvas|if present]]. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.}}
 +
{{param|boolean|cleardepth|Whether to clear the active depth buffer, [[love.graphics.setCanvas|if present]]. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.}}
 +
=== Returns ===
 +
Nothing.
  
 
== Examples ==
 
== Examples ==
Line 63: Line 88:
 
         -- Draw lines from the screen's origin to a random x and y coordinate.
 
         -- Draw lines from the screen's origin to a random x and y coordinate.
 
         local rx, ry = love.math.random( 0, love.graphics.getWidth() ), love.math.random( 0, love.graphics.getHeight() )
 
         local rx, ry = love.math.random( 0, love.graphics.getWidth() ), love.math.random( 0, love.graphics.getHeight() )
−
         love.graphics.setColor( love.math.random( 255 ), 0, 0 )
+
         love.graphics.setColor( love.math.random( ), 0, 0 )
 
         love.graphics.line( 0, 0, rx, ry )
 
         love.graphics.line( 0, 0, rx, ry )
−
         love.graphics.setColor( 255, 255, 255 )
+
         love.graphics.setColor( 1, 1, 1 )
 
     end)
 
     end)
 
end
 
end
Line 88: Line 113:
 
[[Category:Functions]]
 
[[Category:Functions]]
 
[[Sub-Category::Drawing| ]]
 
[[Sub-Category::Drawing| ]]
−
{{#set:Description=Clears the screen to background color.}}
+
{{#set:Description=Clears the screen or active [[Canvas]] to the specified color.}}
 
{{#set:Since=000}}
 
{{#set:Since=000}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.graphics.clear}}
 
{{i18n|love.graphics.clear}}

Latest revision as of 23:24, 3 April 2018

Clears the screen or active Canvas to the specified color.

This function is called automatically before love.draw in the default love.run function. See the example in love.run for a typical use of this function.

Note that the scissor area bounds the cleared region.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

In versions prior to 0.10.0, this function clears the screen to the currently set background color instead.

Function

Clears the screen to the background color in 0.9.2 and earlier, or to transparent black (0, 0, 0, 0) in LÖVE 0.10.0 and newer.

Synopsis

love.graphics.clear( )

Arguments

None.

Returns

Nothing.

Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Clears the screen or active Canvas to the specified color.

Synopsis

love.graphics.clear( r, g, b, a, clearstencil, cleardepth )

Arguments

number r
The red channel of the color to clear the screen to.
number g
The green channel of the color to clear the screen to.
number b
The blue channel of the color to clear the screen to.
number a (1)
The alpha channel of the color to clear the screen to.
Available since LÖVE 11.0
boolean clearstencil (true)
Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
boolean cleardepth (true)
Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.


Returns

Nothing.

Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Clears multiple active Canvases to different colors, if multiple Canvases are active at once via love.graphics.setCanvas.

Synopsis

love.graphics.clear( color, ..., clearstencil, cleardepth )

Arguments

table color
A table in the form of {r, g, b, a} containing the color to clear the first active Canvas to.
table ...
Additional tables for each active Canvas.
Available since LÖVE 11.0
boolean clearstencil (true)
Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
boolean cleardepth (true)
Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.

Returns

Nothing.

Notes

A color must be specified for each active Canvas, when this function variant is used.

Function

Available since LÖVE 11.0
This variant is not supported in earlier versions.

Clears the stencil or depth buffers without having to clear the color canvas as well.

Synopsis

love.graphics.clear( clearcolor, clearstencil, cleardepth )

Arguments

boolean clearcolor
Whether to clear the active color canvas to transparent black (0, 0, 0, 0). Typically this should be set to false with this variant of the function.
boolean clearstencil
Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
boolean cleardepth
Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.

Returns

Nothing.

Examples

Clear canvas before drawing

If the c-key is pressed the canvas will be cleared before drawing a new line on the screen. 

local canvas = love.graphics.newCanvas()
local clear

function love.update()
    -- Use an anonymous function to draw lines on our canvas.
    canvas:renderTo( function()
        if clear then
            love.graphics.clear() -- Clear the canvas before drawing lines.
        end

        -- Draw lines from the screen's origin to a random x and y coordinate.
        local rx, ry = love.math.random( 0, love.graphics.getWidth() ), love.math.random( 0, love.graphics.getHeight() )
        love.graphics.setColor( love.math.random( ), 0, 0 )
        love.graphics.line( 0, 0, rx, ry )
        love.graphics.setColor( 1, 1, 1 )
    end)
end

function love.draw()
    love.graphics.draw( canvas )
end

function love.keypressed( key )
    if key == "c" then
        clear = not clear
    end
end

See Also


Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info

Retrieved from "https://love2d.org./w/index.php?title=love.graphics.clear&oldid=21344"