Difference between revisions of "Canvas"

(Canvases do not auto-pad, this is intentional. It's likely that all implementations supporting framebuffers have the non-po2 textures extension, though. Added a less-in-your-face notice.)
m
(22 intermediate revisions by 9 users not shown)
Line 4: Line 4:
 
By drawing things that do not change position often (such as background items) to the Canvas, and then drawing the entire Canvas instead of each item,  you can reduce the number of draw operations performed each frame.
 
By drawing things that do not change position often (such as background items) to the Canvas, and then drawing the entire Canvas instead of each item,  you can reduce the number of draw operations performed each frame.
  
Canvases can be susceptible to [[PO2_Syndrome| power of 2 syndrome]]. Most graphics cards that support Canvas should have PO2 texture support. However, there are some old cards that do not. Check with [[love.graphics.isSupported|love.graphics.isSupported("npot")]] if it is supported.
+
In versions prior to [[0.10.0]], not all graphics cards that LÖVE supported could use Canvases. [[love.graphics.isSupported|love.graphics.isSupported("canvas")]] could be used to check for support at runtime.
 +
 
 +
 
 +
{{notice|When drawing content to a Canvas using regular alpha blending, the alpha values of the content get multiplied with its RGB values.
 +
 
 +
Therefore the Canvas' pixel colors will have ''premultiplied alpha'' once it has been drawn to, so when drawing the Canvas to the screen or to another Canvas you must use premultiplied alpha blending – [[love.graphics.setBlendMode]]("alpha", "premultiplied").}}
  
 
== Constructors ==
 
== Constructors ==
Line 10: Line 15:
 
| headers=hide
 
| headers=hide
 
| default=None.
 
| default=None.
 +
| format=template
 +
| template=ListingFields
 +
| introtemplate=ListingIntro
 +
| outrotemplate=ListingOutro
 
| ?Description
 
| ?Description
 +
| ?PrettySince
 +
| ?PrettyRemoved
 +
| ?PrettyDeprecated
 
}}
 
}}
 
== Functions ==
 
== Functions ==
{{#ask: [[Category:Functions]] [[parent::Canvas||Drawable||Object]] [[Concept:Current]]
+
{{#ask: [[Category:Functions]] [[parent::Canvas||Texture||Drawable||Object]] [[Concept:Current]]
 +
| headers=hide
 +
| format=template
 +
| template=ListingFields
 +
| introtemplate=ListingIntro
 +
| outrotemplate=ListingOutro
 +
| ?Description
 +
| ?PrettySince
 +
| ?PrettyRemoved
 +
| ?PrettyDeprecated
 +
}}
 +
== Enums ==
 +
{{#ask: [[Category:Enums]] [[parent::Canvas]] [[Concept:Current]]
 
| headers=hide
 
| headers=hide
 +
| format=template
 +
| template=ListingFields
 +
| introtemplate=ListingIntro
 +
| outrotemplate=ListingOutro
 
| ?Description
 
| ?Description
 +
| ?PrettySince
 +
| ?PrettyRemoved
 +
| ?PrettyDeprecated
 
}}
 
}}
 
== Supertypes ==
 
== Supertypes ==
 +
* [[parent::Texture]]
 
* [[parent::Drawable]]
 
* [[parent::Drawable]]
 
* [[parent::Object]]
 
* [[parent::Object]]
 
== Examples ==
 
== Examples ==
=== sample from the forum ===
+
=== Drawing something to the Canvas and then draw the Canvas to the screen. ===
http://love2d.org/forums/viewtopic.php?f=4&t=2136&start=20
+
<source lang="lua">
 +
function love.load()
 +
    canvas = love.graphics.newCanvas(800, 600)
 +
 
 +
    -- Rectangle is drawn to the canvas with the regular alpha blend mode.
 +
    love.graphics.setCanvas(canvas)
 +
        love.graphics.clear()
 +
        love.graphics.setBlendMode("alpha")
 +
        love.graphics.setColor(1, 0, 0, 0.5)
 +
        love.graphics.rectangle('fill', 0, 0, 100, 100)
 +
    love.graphics.setCanvas()
 +
end
 +
 
 +
function love.draw()
 +
    -- very important!: reset color before drawing to canvas to have colors properly displayed
 +
    -- see discussion here: https://love2d.org/forums/viewtopic.php?f=4&p=211418#p211418
 +
    love.graphics.setColor(1, 1, 1, 1)
 +
 
 +
    -- The rectangle from the Canvas was already alpha blended.
 +
    -- Use the premultiplied alpha blend mode when drawing the Canvas itself to prevent improper blending.
 +
    love.graphics.setBlendMode("alpha", "premultiplied")
 +
    love.graphics.draw(canvas)
 +
    -- Observe the difference if the Canvas is drawn with the regular alpha blend mode instead.
 +
    love.graphics.setBlendMode("alpha")
 +
    love.graphics.draw(canvas, 100, 0)
 +
 
 +
    -- Rectangle is drawn directly to the screen with the regular alpha blend mode.
 +
    love.graphics.setBlendMode("alpha")
 +
    love.graphics.setColor(1, 0, 0, 0.5)
 +
    love.graphics.rectangle('fill', 200, 0, 100, 100)
 +
end
 +
</source>
  
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 
* [[love.graphics.setCanvas]]
 
* [[love.graphics.setCanvas]]
 +
* [[love.graphics.setBlendMode]]
 +
* [[love.graphics.isSupported]]
 
[[Category:Types]]
 
[[Category:Types]]
 
{{#set:Description=Off-screen render target.}}
 
{{#set:Description=Off-screen render target.}}

Revision as of 02:57, 17 July 2019

Available since LÖVE 0.8.0
It has been renamed from Framebuffer.

A Canvas is used for off-screen rendering. Think of it as an invisible screen that you can draw to, but that will not be visible until you draw it to the actual visible screen. It is also known as "render to texture".

By drawing things that do not change position often (such as background items) to the Canvas, and then drawing the entire Canvas instead of each item, you can reduce the number of draw operations performed each frame.

In versions prior to 0.10.0, not all graphics cards that LÖVE supported could use Canvases. love.graphics.isSupported("canvas") could be used to check for support at runtime.


O.png When drawing content to a Canvas using regular alpha blending, the alpha values of the content get multiplied with its RGB values.

Therefore the Canvas' pixel colors will have premultiplied alpha once it has been drawn to, so when drawing the Canvas to the screen or to another Canvas you must use premultiplied alpha blending – love.graphics.setBlendMode("alpha", "premultiplied").

 


Constructors

love.graphics.newCanvas Creates a new Canvas. Added since 0.8.0

Functions

Canvas:clear Clears the contents of a Canvas to a specific color. Added since 0.8.0 Removed in 0.10.0
Canvas:generateMipmaps Generates mipmaps for the Canvas, based on the contents of the highest-resolution mipmap level. Added since 11.0
Canvas:getFSAA Gets the number of FSAA samples used when drawing to the Canvas. Added since 0.9.1 Removed in 0.10.0
Canvas:getFormat Gets the texture format of the Canvas. Added since 0.9.1 Removed in 11.0
Canvas:getImageData Generates ImageData from the contents of the Canvas. Added since 0.8.0 Removed in 0.10.0
Canvas:getMSAA Gets the number of MSAA samples used when drawing to the Canvas. Added since 0.9.2
Canvas:getMipmapMode Gets the MipmapMode this Canvas was created with. Added since 11.0
Canvas:getPixel Gets the pixel at the specified position in a Canvas. Added since 0.9.0 Removed in 0.10.0
Canvas:newImageData Generates ImageData from the contents of the Canvas. Added since 0.10.0
Canvas:renderTo Render to a Canvas using a function. Added since 0.8.0
Object:release Immediately destroys the object's Lua reference. Added since 11.0
Object:type Gets the type of the object as a string.
Object:typeOf Checks whether an object is of a certain type.
Texture:getDPIScale Gets the DPI scale factor of the Texture. Added since 11.0
Texture:getDepth Gets the depth of a Volume Texture. Added since 11.0
Texture:getDepthSampleMode Gets the comparison mode used when sampling from a depth texture in a shader. Added since 11.0
Texture:getDimensions Gets the width and height of the Texture. Added since 0.9.0
Texture:getFilter Gets the filter mode of the Texture.
Texture:getFormat Gets the pixel format of the Texture. Added since 11.0
Texture:getHeight Gets the height of the Texture.
Texture:getLayerCount Gets the number of layers / slices in an Array Texture. Added since 11.0
Texture:getMipmapCount Gets the number of mipmaps contained in the Texture. Added since 11.0
Texture:getMipmapFilter Gets the mipmap filter mode for a Texture. Added since 0.9.0
Texture:getPixelDimensions Gets the width and height in pixels of the Texture. Added since 11.0
Texture:getPixelHeight Gets the height in pixels of the Texture. Added since 11.0
Texture:getPixelWidth Gets the width in pixels of the Texture. Added since 11.0
Texture:getTextureType Gets the type of the Texture. Added since 11.0
Texture:getWidth Gets the width of the Texture.
Texture:getWrap Gets the wrapping properties of a Texture.
Texture:isReadable Gets whether the Texture can be drawn and sent to a Shader. Added since 11.0
Texture:setDepthSampleMode Sets the comparison mode used when sampling from a depth texture in a shader. Added since 11.0
Texture:setFilter Sets the filter mode of the Texture.
Texture:setMipmapFilter Sets the mipmap filter mode for a Texture. Added since 0.9.0
Texture:setWrap Sets the wrapping properties of a Texture.

Enums

MipmapMode Controls whether a Canvas has mipmaps, and its behaviour when it does. Added since 11.0

Supertypes

Examples

Drawing something to the Canvas and then draw the Canvas to the screen.

function love.load()
    canvas = love.graphics.newCanvas(800, 600)

    -- Rectangle is drawn to the canvas with the regular alpha blend mode.
    love.graphics.setCanvas(canvas)
        love.graphics.clear()
        love.graphics.setBlendMode("alpha")
        love.graphics.setColor(1, 0, 0, 0.5)
        love.graphics.rectangle('fill', 0, 0, 100, 100)
    love.graphics.setCanvas()
end

function love.draw()
    -- very important!: reset color before drawing to canvas to have colors properly displayed
    -- see discussion here: https://love2d.org/forums/viewtopic.php?f=4&p=211418#p211418
    love.graphics.setColor(1, 1, 1, 1)

    -- The rectangle from the Canvas was already alpha blended.
    -- Use the premultiplied alpha blend mode when drawing the Canvas itself to prevent improper blending.
    love.graphics.setBlendMode("alpha", "premultiplied")
    love.graphics.draw(canvas)
    -- Observe the difference if the Canvas is drawn with the regular alpha blend mode instead.
    love.graphics.setBlendMode("alpha")
    love.graphics.draw(canvas, 100, 0)

    -- Rectangle is drawn directly to the screen with the regular alpha blend mode.
    love.graphics.setBlendMode("alpha")
    love.graphics.setColor(1, 0, 0, 0.5)
    love.graphics.rectangle('fill', 200, 0, 100, 100)
end

See Also


Other Languages