love.graphics.discard

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

Discards (trashes) the contents of the screen or active Canvas. This is a performance optimization function with niche use cases.

If the active Canvas has just been changed and the "replace" BlendMode is about to be used to draw something which covers the entire screen, calling love.graphics.discard rather than calling love.graphics.clear or doing nothing may improve performance on mobile devices.

On some desktop systems this function may do nothing.

This function effectively replaces the contents of the screen or active Canvas with garbage. Most BlendModes, including the default "alpha" blend mode, blend what's drawn with the contents of the screen - which would cause unexpected glitches if this function is used inappropriately.

Function

Synopsis

love.graphics.discard( discardcolor, discardstencil )

Arguments

boolean discardcolor (true)

Whether to discard the texture(s) of the active Canvas(es) (the contents of the screen if no Canvas is active.)

boolean discardstencil (true)

Whether to discard the contents of the stencil buffer of the screen / active Canvas.

Returns

Nothing.

Function

Synopsis

love.graphics.discard( discardcolors, discardstencil )

Arguments

table discardcolors

An array containing boolean values indicating whether to discard the texture of each active Canvas, when multiple simultaneous Canvases are active.

boolean discardstencil (true)

Whether to discard the contents of the stencil buffer of the screen / active Canvas.

Returns

Nothing.

See Also

• love.graphics
• love.graphics.clear
• Canvas
• love.graphics.setBlendMode