- Each canvas (and the screen) has an invisible stencil value associated with each pixel. Stencil values are between [0, 255].
- love.graphics.stencil takes a function argument which draws things, and makes the geometry of what's drawn set the stencil values of pixels instead of coloring the pixels.
- Its second argument is a 'stencil action' which determines what happens to the stencil values of pixels. The possible stencil actions are 'replace' (the default), 'invert', 'increment', 'decrement', 'incrementwrap', and 'decrementwrap'. If the stencil action is 'replace', the third argument of love.graphics.stencil is a number between [0, 255] which determines what the stencil value of each pixel that touches drawn objects is replaced with.
The fourth argument is a boolean which determines whether the previous stencil values of all pixels on-screen should be kept (true), or cleared to 0 (false, the default.) love.graphics.clear also clears the stencil values.
- love.graphics.setStencilTest allows for anything drawn to be affected by a comparison between the arguments to setStencilTest and the existing stencil value of the pixels that are touched by what's drawn. Its first argument is a compare mode which can be 'equal', 'notequal', 'less', 'lequal', 'gequal', or 'greater', and the second argument is an integer value (between 0 and 255) used in the comparison with the value in the stencil buffer.
For example, love.graphics.setStencilTest("greater", 0) will cause any geometry drawn afterwards to only appear on pixels whose stencil value is greater than 0.
The basic APIs are:
video = love.graphics.newVideo("myvideo.ogv")
love.graphics.draw(video, ...) -- Video objects are Drawables.
video:play(), video:pause()
video:getDuration(), video:tell(), video:rewind(), video:seek(seconds)
video:getSource()
video:getWidth(), video:getHeight(), video:setFilter(min, mag)
More advanced APIs include video:setSource(source), video:getStream(), and videostream:setSync.
To use a custom pixel shader when drawing a Video, call the new TexelVideo(texcoords) function instead of Texel(texture, texcoords) in order to get the pixel colors of a video frame.
The aforementioned functions now optionally accept an array instead of a plain string. The array is in the format of: {{r, g, b [, a]}, "first colored text, ", {r, g, b [, a]}, "second colored text", ...}, where the color values specify the color to use in the next section of the text.
Gamma-correct blending and shader math can be enabled globally via the new 't.gammacorrect' boolean flag in love.conf.
The new function love.graphics.isGammaCorrect will return true if it was requested in love.conf and is supported on the system.
When gamma correct rendering is enabled, colors (including the colors of pixels from images) are automatically converted from sRGB to linear RGB before use. When drawing to the main screen or to a canvas with the 'normal' or 'srgb' format, the final output colors of pixel shaders are automatically converted from linear RGB to sRGB after blending and before the color is stored in the pixel.
This lets the rendering pipeline do math using linear RGB values for colors rather than sRGB values, so the math is correct, without making users of the APIs manually linearize their colors with the love.math.gammaToLinear function (which still exists). The final output of the screen is encoded as sRGB, which is what systems expect. Canvases (except when otherwise requested) store their contents with sRGB encoding for increased precision with darker colors.
the 'srgb' window setting flag has been removed, as well as the 'srgb' image flag. A new image flag 'linear' has been added, which when set to true will cause the colors of the image to always be treated as linear RGB rather than sRGB, when gamma-correct rendering is enabled.
A new function 'Shader:sendColor' has been added, which has the same argument structure as 'Shader:send' but expects colors in the range of [0, 255]. When gamma-correct rendering is enabled it automatically gamma-corrects the given colors (by applying gammaToLinear to them.)
New shader code functions have been added: gammaToLinear, linearToGamma, gammaCorrectColor, and unGammaCorrectColor. When gamma-correct rendering is enabled, the LOVE_GAMMA_CORRECT #define is set and gammaCorrectColor and unGammaCorrectColor are aliases for gammaToLinear and linearToGamma respectively, otherwise the functions do nothing.
The new shader functions have 'precise' and 'fast' variants. If the LOVE_PRECISE_GAMMA define is set, then the normal functions default to the precise variants, otherwise they default to the fast variants. Currently the define is set in vertex shaders and not set in pixel shaders.
The default per-vertex color is automatically gamma-corrected by LÖVE when gamma correct rendering is enabled, but any custom named per-vertex attribute specified with the new custom attribute Mesh functionality won't be, unless 'gammaCorrectColor' or similar functions are explicitly used (preferably inside the vertex shader code that has the custom attribute.)
All mipmap levels must be present if custom mipmaps are used (and their sizes must be half the size of the previous mipmap level, rounded down.)
Image:getData now returns all custom mipmaps in an Image.
Removed the 'premultiplied' blend mode, since setBlendMode("alpha", false) accomplishes the same thing now.
The 'multiply' blend mode is unaffected by the new flag, since fixed-function hardware blending can't do the equivalent of setBlendMode("multiply", true).
Added new love.graphics.newMesh variants: newMesh(vertexformat, vertices [, drawmode, meshusage]) and newMesh(vertexformat, numvertices [, drawmode, meshusage]).
Replaced the regular love.graphics.newMesh variants with newMesh(vertices [, drawmode, meshusage]) and newMesh(numvertices [, drawmode, meshusage]). To use an image or canvas with a mesh, use Mesh:setTexture.
vertexformat is a table with the following prototype:
{
{attributename, datatype, components},
{attributename, datatype, components},
...
}
Where attributename is the name of the vertex attribute (can be the built-in names 'VertexPosition', 'VertexTexCoord', or 'VertexColor', or a custom name for use in a vertex shader), datatype is the type of values used for the attribute ('float' or 'byte'), and components is the number of components in the vertex attribute (between 1 and 4.)
The vertex format is used to determine the layout of the vertices in the mesh, for example the 'regular' newMesh variants use this vertex format:
format = {
{"VertexPosition", "float", 2},
{"VertexTexCoord", "float", 2},
{"VertexColor", "byte", 4},
}
The mesh usage parameter accepts the same constants as the spritebatch usage hint in love.graphics.newSpriteBatch - "dynamic", "static", and "stream".
Mesh:setVertex now sets *all* vertex attributes for a specific vertex in the Mesh.
Added Mesh:setVertexAttribute(vertexindex, attributeindex, attributevalue1, ...), which sets the values for a specific vertex attribute in a specific vertex in the Mesh (resolves issue #784.)
Added Mesh:getVertexFormat and Mesh:flush.
Added Mesh:setAttributeEnabled(attributename, enable) and Mesh:isAttributeEnabled(attributename), to enable or disable the use of a specific attribute when drawing the Mesh.
Added Mesh:attachAttribute(attributename, mesh), which makes the Mesh use a vertex attribute from another mesh when drawing the Mesh. This can be used to separate out vertex attributes which are updated at different rates into different meshes, and to share vertex data between multiple meshes.
Removed Mesh:setVertices, Mesh:getVertices, and Mesh:setVertexColors.
Renamed the love.image CompressedData type to CompressedImageData.
love.math.compress returns a love.math CompressedData object which holds the newly compressed data. Currently supported formats are "lz4" and "zlib". Note that the formats are not file formats and don't compress filesystem hierarchies.
Using it just after activating a Canvas can improve performance on many mobile devices, if the conditions for using it are right.
--HG--
branch : minor
Text objects are Drawable objects that represent text on the screen. They decouple text drawing from text parsing and vertex uploading, in a similar manner to SpriteBatches. They also optionally allow efficient batching of text from the same Font in different relative coordinate transformations, without having many draw calls.
Text objects currently have the following methods:
Text:set(textstring) -- replaces any existing text in the object with the new string.
Text:setf(textstring, wraplimit, alignmode) -- replaces any existing text with formatted text using the new string.
Text:getFont() -- gets the Font object used for this Text object.
Text:getWidth() -- gets the width in pixels of the most recently added text in the Text object.
Text:getHeight() -- gets the height in pixels of the most recently added text in the Text object.
Text:add(textstring, x, y, angle, sx, sy, ox, oy, kx, ky) -- adds a new string to the text object using the specified relative coordinate transformation, without replacing existing text. This behaves much like SpriteBatch:add.
Text:addf(textstring, wraplimit, alignmode, x, y, angle, sx, sy, ox, oy, kx, ky) -- adds a new formatted string to the text object using the specified relative coordinate transformation.
Text:clear() -- clears all text from the object.
--HG--
branch : minor
If the LOVE_GRAPHICS_USE_OPENGLES environment variable is set, then love will try to create an OpenGL ES context before falling back to regular OpenGL. If it's not set (or set to 0), then the opposite happens except when love is run on backends that should always use OpenGL ES.
--HG--
branch : minor
drawcalls: The number of internal draw calls made so far in the current frame.
canvasswitches: The number of times the active Canvas has been changed so far in the current frame.
texturememory: The approximate amount of video memory (in bytes) used by OpenGL textures created by Images, Canvases, and Fonts.
images: The number of active Image objects.
canvases: The number of active Canvas objects.
fonts: The number of active Font objects.
Draw to the stencil buffer (rather than the color buffer) using love.graphics.drawStencil with a function which draws geometry. Once the stencil buffer has been drawn to, use love.graphics.setStencilTest before drawing to let drawn geometry be affected by it.
love.graphics.clear (and Canvas:clear) will clear both the color and stencil buffers by default. love.graphics.clear("stencil") will clear only the stencil buffer.
--HG--
branch : stencil-functions
Alex Szpakowski
Bart van Strien
muddmaker