Difference between revisions of "love.graphics.setCanvas"

m (→‎Function: Edited notes for the new love.graphics.setCanvas variant)
m
 
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{newin|[[0.8.0]]|080|type=function|text=It has been renamed from [[love.graphics.setRenderTarget]]}}
 
{{newin|[[0.8.0]]|080|type=function|text=It has been renamed from [[love.graphics.setRenderTarget]]}}
 +
Captures drawing operations to a [[Canvas]].
 
== Function ==
 
== Function ==
 +
Sets the render target to a specified [[Canvas]]. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the [[Canvas]] and not shown on the screen.
 +
 +
When using a [[love.graphics.stencil|stencil]] or [[love.graphics.setDepthMode|depth testing]] with an active Canvas, the stencil buffer or depth buffer must be explicitly enabled in setCanvas via the variants below.
 +
 +
Note that no canvas should be active when ''[[love.graphics.present]]'' is called. ''love.graphics.present'' is called at the end of [[love.draw]] in the default [[love.run]], hence if you activate a canvas using this function, you normally need to deactivate it at some point before ''love.draw'' finishes.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.graphics.setCanvas( canvas )
+
love.graphics.setCanvas( canvas, mipmap )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
 
{{param|Canvas|canvas|The new target.}}
 
{{param|Canvas|canvas|The new target.}}
 +
{{New feature|11.0|
 +
{{param|number|mipmap (1)|The mipmap level to render to, for Canvases with [[Texture:getMipmapCount|mipmaps]].}}
 +
}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
−
=== Notes ===
 
−
Sets the render target to a specified [[Canvas]]. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the [[Canvas]] and not shown on the screen.
 
  
 
== Function ==
 
== Function ==
 +
Resets the render target to the screen, i.e. re-enables drawing to the screen.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Line 21: Line 29:
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
−
=== Notes ===
 
−
Resets the render target to the screen, i.e. re-enables drawing to the screen.
 
  
 
== Function ==
 
== Function ==
 
{{newin|[[0.9.0]]|090|type=variant}}
 
{{newin|[[0.9.0]]|090|type=variant}}
 +
Sets the render target to multiple simultaneous [[TextureType|2D]] [[Canvas]]es. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the specified canvases and not shown on the screen.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Line 37: Line 44:
 
Nothing.
 
Nothing.
 
=== Notes ===
 
=== Notes ===
−
Sets the render target to multiple simultaneous [[Canvas]]es. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the specified canvases and not shown on the screen.
+
Normally all drawing operations will draw only to the first canvas passed to the function, but that can be changed if a [[Shader|pixel shader]] is used with the [[love.graphics.newShader#Pixel_Shader_Function|<code>void effect</code> function]] instead of the regular <code>vec4 effect</code>.
 +
 
 +
All canvas arguments must have the same widths and heights and the same [[TextureMode|texture type]]. Not all computers which support Canvases will support multiple render targets. If [[love.graphics.isSupported|love.graphics.isSupported("multicanvas")]] returns true, at least 4 simultaneously active canvases are supported.
  
−
All canvas arguments must have the same widths and heights and the same [[TextureMode|texture type]]. Normally the same thing will be drawn on each canvas, but that can be changed if a [[Shader|pixel shader]] is used with the <code>[[love.graphics.newShader#Pixel_Shader_Function|effects]]</code> function instead of the regular <code>effect</code>.
+
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
Sets the render target to the specified [[TextureType|layer/slice]] and [[Texture:getMipmapCount|mipmap level]] of the given non-2D [[Canvas]]. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the [[Canvas]] and not shown on the screen.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.setCanvas( canvas, slice, mipmap )
 +
</source>
 +
=== Arguments ===
 +
{{param|Canvas|canvas|The new render target.}}
 +
{{param|number|slice|For cubemaps this is the cube face index to render to (between 1 and 6). For Array textures this is the [[Texture:getLayerCount|array layer]]. For volume textures this is the depth slice. 2D canvases should use a value of 1.}}
 +
{{param|number|mipmap (1)|The mipmap level to render to, for Canvases with [[Texture:getMipmapCount|mipmaps]].}}
 +
=== Returns ===
 +
Nothing.
  
−
Not all computers which support Canvases will support multiple render targets. If [[love.graphics.isSupported|love.graphics.isSupported("multicanvas")]] returns true, at least 4 simultaneously active canvases are supported.
+
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
Sets the active render target(s) and active stencil and depth buffers based on the specified setup information. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the specified [[Canvas]]es and not shown on the screen.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.setCanvas( setup )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|setup|A table specifying the active Canvas(es), their mipmap levels and active layers if applicable, and whether to use a stencil and/or depth buffer.}}
 +
{{subparam|RenderTargetSetup|[1]|The Canvas to render to.}}
 +
{{subparam|RenderTargetSetup|[2] (nil)|An additional Canvas to render to, if multiple simultaneous render targets are wanted.}}
 +
{{subparam|RenderTargetSetup|...|Additional Canvases to render to, if multiple simultaneous render targets are wanted.}}
 +
{{subparam|boolean|stencil (false)|Whether an internally managed stencil buffer should be used, if the <code>depthstencil</code> field isn't set.}}
 +
{{subparam|boolean|depth (false)|Whether an internally managed depth buffer should be used, if the <code>depthstencil</code> field isn't set.}}
 +
{{subparam|RenderTargetSetup|depthstencil (nil)|An optional custom depth/stencil [[PixelFormat|formatted]] Canvas to use for the depth and/or stencil buffer.}}
 +
=== Returns ===
 +
Nothing.
 +
=== Notes ===
 +
The <code>RenderTargetSetup</code> parameters can either be a [[Canvas]] object, or a table in the following format: <code>{canvas, mipmap=#, layer=#, face=#}</code>
 +
{{param|Canvas|[1]|The Canvas to use for this active render target.}}
 +
{{param|number|mipmap (1)|The mipmap level to render to, for Canvases with [[Texture:getMipmapCount|mipmaps]].}}
 +
{{param|number|layer (1)|Only used for [[TextureType|Volume and Array]]-type Canvases. For Array textures this is the [[Texture:getLayerCount|array layer]] to render to. For volume textures this is the depth slice.}}
 +
{{param|number|face (1)|Only used for [[TextureType|Cubemap]]-type Canvases. The cube face index to render to (between 1 and 6)}}
  
 
== Examples ==
 
== Examples ==
Line 54: Line 97:
  
 
     -- draw colored square to canvas
 
     -- draw colored square to canvas
−
     love.graphics.setColor(230,240,120)
+
     love.graphics.setColor(0.8, 0.9, 0.4)
−
     love.graphics.rectangle('fill',0,0,100,100)
+
     love.graphics.rectangle("fill", 0, 0, 100, 100)
  
 
     -- re-enable drawing to the main screen
 
     -- re-enable drawing to the main screen
Line 63: Line 106:
 
function love.draw()
 
function love.draw()
 
     -- draw scaled canvas to screen
 
     -- draw scaled canvas to screen
−
     love.graphics.setColor(255,255,255)
+
     love.graphics.setColor(1, 1, 1)
−
     love.graphics.draw(canvas, 200,100, 0, .5,.5)
+
     love.graphics.draw(canvas, 200, 100, 0, 0.5, 0.5)
 
end
 
end
 +
</source>
 +
 +
 +
=== Advanced setup with the table variant of love.graphics.setCanvas ===
 +
<source lang="lua">
 +
-- Allow love.graphics.stencil calls when drawing to the given Canvas.
 +
love.graphics.setCanvas({canvas, stencil=true})
 +
 +
-- Use multiple simultaneous render targets when drawing to several canvases of the Array Texture type,
 +
-- and use a custom depth buffer as well.
 +
canvas1 = love.graphics.newCanvas(128, 128, 4, {type="array"})
 +
canvas2 = love.graphics.newCanvas(128, 128, 8, {type="array"})
 +
depthcanvas = love.graphics.newCanvas(128, 128, {format="depth24", readable=true})
 +
 +
love.graphics.setCanvas({
 +
    {canvas1, layer = 3},
 +
    {canvas2, layer = 1},
 +
    depthstencil = depthcanvas,
 +
})
 
</source>
 
</source>
  
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 +
* [[love.graphics.getCanvas]]
 
* [[Canvas]]
 
* [[Canvas]]
−
* [[love.graphics.getCanvas]]
 
 
* [[Canvas:renderTo]]
 
* [[Canvas:renderTo]]
 
[[Category:Functions]]
 
[[Category:Functions]]

Latest revision as of 17:41, 28 May 2019

Available since LÖVE 0.8.0
It has been renamed from love.graphics.setRenderTarget.

Captures drawing operations to a Canvas.

Function

Sets the render target to a specified Canvas. All drawing operations until the next love.graphics.setCanvas call will be redirected to the Canvas and not shown on the screen.

When using a stencil or depth testing with an active Canvas, the stencil buffer or depth buffer must be explicitly enabled in setCanvas via the variants below.

Note that no canvas should be active when love.graphics.present is called. love.graphics.present is called at the end of love.draw in the default love.run, hence if you activate a canvas using this function, you normally need to deactivate it at some point before love.draw finishes.

Synopsis

love.graphics.setCanvas( canvas, mipmap )

Arguments

Canvas canvas
The new target.
Available since LÖVE 11.0
number mipmap (1)
The mipmap level to render to, for Canvases with mipmaps.

Returns

Nothing.

Function

Resets the render target to the screen, i.e. re-enables drawing to the screen.

Synopsis

love.graphics.setCanvas( )

Arguments

None.

Returns

Nothing.

Function

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

Sets the render target to multiple simultaneous 2D Canvases. All drawing operations until the next love.graphics.setCanvas call will be redirected to the specified canvases and not shown on the screen.

Synopsis

love.graphics.setCanvas( canvas1, canvas2, ... )

Arguments

Canvas canvas1
The first render target.
Canvas canvas2
The second render target.
Canvas ...
More canvases.

Returns

Nothing.

Notes

Normally all drawing operations will draw only to the first canvas passed to the function, but that can be changed if a pixel shader is used with the void effect function instead of the regular vec4 effect.

All canvas arguments must have the same widths and heights and the same texture type. Not all computers which support Canvases will support multiple render targets. If love.graphics.isSupported("multicanvas") returns true, at least 4 simultaneously active canvases are supported.

Function

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

Sets the render target to the specified layer/slice and mipmap level of the given non-2D Canvas. All drawing operations until the next love.graphics.setCanvas call will be redirected to the Canvas and not shown on the screen.

Synopsis

love.graphics.setCanvas( canvas, slice, mipmap )

Arguments

Canvas canvas
The new render target.
number slice
For cubemaps this is the cube face index to render to (between 1 and 6). For Array textures this is the array layer. For volume textures this is the depth slice. 2D canvases should use a value of 1.
number mipmap (1)
The mipmap level to render to, for Canvases with mipmaps.

Returns

Nothing.

Function

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

Sets the active render target(s) and active stencil and depth buffers based on the specified setup information. All drawing operations until the next love.graphics.setCanvas call will be redirected to the specified Canvases and not shown on the screen.

Synopsis

love.graphics.setCanvas( setup )

Arguments

table setup
A table specifying the active Canvas(es), their mipmap levels and active layers if applicable, and whether to use a stencil and/or depth buffer.
RenderTargetSetup [1]
The Canvas to render to.
RenderTargetSetup [2] (nil)
An additional Canvas to render to, if multiple simultaneous render targets are wanted.
RenderTargetSetup ...
Additional Canvases to render to, if multiple simultaneous render targets are wanted.
boolean stencil (false)
Whether an internally managed stencil buffer should be used, if the depthstencil field isn't set.
boolean depth (false)
Whether an internally managed depth buffer should be used, if the depthstencil field isn't set.
RenderTargetSetup depthstencil (nil)
An optional custom depth/stencil formatted Canvas to use for the depth and/or stencil buffer.

Returns

Nothing.

Notes

The RenderTargetSetup parameters can either be a Canvas object, or a table in the following format: {canvas, mipmap=#, layer=#, face=#}

Canvas [1]
The Canvas to use for this active render target.
number mipmap (1)
The mipmap level to render to, for Canvases with mipmaps.
number layer (1)
Only used for Volume and Array-type Canvases. For Array textures this is the array layer to render to. For volume textures this is the depth slice.
number face (1)
Only used for Cubemap-type Canvases. The cube face index to render to (between 1 and 6)

Examples

Drawing to a canvas

function love.load()
    -- create canvas
    canvas = love.graphics.newCanvas()

    -- direct drawing operations to the canvas
    love.graphics.setCanvas(canvas)

    -- draw colored square to canvas
    love.graphics.setColor(0.8, 0.9, 0.4)
    love.graphics.rectangle("fill", 0, 0, 100, 100)

    -- re-enable drawing to the main screen
    love.graphics.setCanvas()
end

function love.draw()
    -- draw scaled canvas to screen
    love.graphics.setColor(1, 1, 1)
    love.graphics.draw(canvas, 200, 100, 0, 0.5, 0.5)
end


Advanced setup with the table variant of love.graphics.setCanvas

-- Allow love.graphics.stencil calls when drawing to the given Canvas.
love.graphics.setCanvas({canvas, stencil=true})

-- Use multiple simultaneous render targets when drawing to several canvases of the Array Texture type,
-- and use a custom depth buffer as well.
canvas1 = love.graphics.newCanvas(128, 128, 4, {type="array"})
canvas2 = love.graphics.newCanvas(128, 128, 8, {type="array"})
depthcanvas = love.graphics.newCanvas(128, 128, {format="depth24", readable=true})

love.graphics.setCanvas({
    {canvas1, layer = 3},
    {canvas2, layer = 1},
    depthstencil = depthcanvas,
})

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.setCanvas&oldid=22740"