diff options
Diffstat (limited to 'meta')
| -rw-r--r-- | meta/3rd/lovr/library/callback.lua | 2 | ||||
| -rw-r--r-- | meta/3rd/lovr/library/lovr/data.lua | 890 | ||||
| -rw-r--r-- | meta/3rd/lovr/library/lovr/event.lua | 3 | ||||
| -rw-r--r-- | meta/3rd/lovr/library/lovr/graphics.lua | 3851 | ||||
| -rw-r--r-- | meta/3rd/lovr/library/lovr/headset.lua | 6 | ||||
| -rw-r--r-- | meta/3rd/lovr/library/lovr/math.lua | 6 |
6 files changed, 2506 insertions, 2252 deletions
diff --git a/meta/3rd/lovr/library/callback.lua b/meta/3rd/lovr/library/callback.lua index 13cbef51..a257b5f6 100644 --- a/meta/3rd/lovr/library/callback.lua +++ b/meta/3rd/lovr/library/callback.lua @@ -35,7 +35,7 @@ lovr.conf = nil --- ---The display is cleared to the background color before this function is called. --- ----@type fun() +---@type fun(pass: lovr.Pass):boolean lovr.draw = nil --- diff --git a/meta/3rd/lovr/library/lovr/data.lua b/meta/3rd/lovr/library/lovr/data.lua index 9c53bab0..811433e7 100644 --- a/meta/3rd/lovr/library/lovr/data.lua +++ b/meta/3rd/lovr/library/lovr/data.lua @@ -269,6 +269,492 @@ function Image:setPixel(x, y, r, g, b, a) end local ModelData = {} --- +---Returns the number of channels in an animation. +--- +---A channel is a set of keyframes for a single property of a node. +--- +---@overload fun(self: lovr.ModelData, name: string):number +---@param index number # The index of an animation. +---@return number count # The number of channels in the animation. +function ModelData:getAnimationChannelCount(index) end + +--- +---Returns the number of animations in the model. +--- +---@return number count # The number of animations in the model. +function ModelData:getAnimationCount() end + +--- +---Returns the duration of an animation. +--- +--- +---### NOTE: +---The duration of the animation is calculated as the latest timestamp of all of its channels. +--- +---@overload fun(self: lovr.ModelData, name: string):number +---@param index number # The index of the animation. +---@return number duration # The duration of the animation, in seconds. +function ModelData:getAnimationDuration(index) end + +--- +---Returns a single keyframe in a channel of an animation. +--- +---@overload fun(self: lovr.ModelData, name: string, channel: number, keyframe: number):number, number +---@param index number # The index of an animation. +---@param channel number # The index of a channel in the animation. +---@param keyframe number # The index of a keyframe in the channel. +---@return number time # The timestamp of the keyframe. +function ModelData:getAnimationKeyframe(index, channel, keyframe) end + +--- +---Returns the number of keyframes in a channel of an animation. +--- +---@overload fun(self: lovr.ModelData, name: string, channel: number):number +---@param index number # The index of an animation. +---@param channel number # The index of a channel in the animation. +---@return number count # The number of keyframes in the channel. +function ModelData:getAnimationKeyframeCount(index, channel) end + +--- +---Returns the name of an animation. +--- +--- +---### NOTE: +---If the animation does not have a name, this function returns `nil`. +--- +---@param index number # The index of the animation. +---@return string name # The name of the animation. +function ModelData:getAnimationName(index) end + +--- +---Returns the index of a node targeted by an animation's channel. +--- +---@overload fun(self: lovr.ModelData, name: string, channel: number):number +---@param index number # The index of an animation. +---@param channel number # The index of a channel in the animation. +---@return number node # The index of the node targeted by the channel. +function ModelData:getAnimationNode(index, channel) end + +--- +---Returns the property targeted by an animation's channel. +--- +---@overload fun(self: lovr.ModelData, name: string, channel: number):lovr.AnimationProperty +---@param index number # The index of an animation. +---@param channel number # The index of a channel in the animation. +---@return lovr.AnimationProperty property # The property (translation, rotation, scale) affected by the keyframes. +function ModelData:getAnimationProperty(index, channel) end + +--- +---Returns the smooth mode of a channel in an animation. +--- +---@overload fun(self: lovr.ModelData, name: string, channel: number):lovr.SmoothMode +---@param index number # The index of an animation. +---@param channel number # The index of a channel in the animation. +---@return lovr.SmoothMode smooth # The smooth mode of the keyframes. +function ModelData:getAnimationSmoothMode(index, channel) end + +--- +---Returns one of the Blobs in the model, by index. +--- +---@param index number # The index of the Blob to get. +---@return lovr.Blob blob # The Blob object. +function ModelData:getBlob(index) end + +--- +---Returns the number of Blobs in the model. +--- +---@return number count # The number of Blobs in the model. +function ModelData:getBlobCount() end + +--- +---Returns the 6 values of the model's axis-aligned bounding box. +--- +---@return number minx # The minimum x coordinate of the vertices in the model. +---@return number maxx # The maximum x coordinate of the vertices in the model. +---@return number miny # The minimum y coordinate of the vertices in the model. +---@return number maxy # The maximum y coordinate of the vertices in the model. +---@return number minz # The minimum z coordinate of the vertices in the model. +---@return number maxz # The maximum z coordinate of the vertices in the model. +function ModelData:getBoundingBox() end + +--- +---Returns a sphere approximately enclosing the vertices in the model. +--- +---@return number x # The x coordinate of the position of the sphere. +---@return number y # The y coordinate of the position of the sphere. +---@return number z # The z coordinate of the position of the sphere. +---@return number radius # The radius of the bounding sphere. +function ModelData:getBoundingSphere() end + +--- +---Returns the center of the model's axis-aligned bounding box, relative to the model's origin. +--- +---@return number x # The x offset of the center of the bounding box. +---@return number y # The y offset of the center of the bounding box. +---@return number z # The z offset of the center of the bounding box. +function ModelData:getCenter() end + +--- +---Returns the depth of the model, computed from its axis-aligned bounding box. +--- +---@return number depth # The depth of the model. +function ModelData:getDepth() end + +--- +---Returns the width, height, and depth of the model, computed from its axis-aligned bounding box. +--- +---@return number width # The width of the model. +---@return number height # The height of the model. +---@return number depth # The depth of the model. +function ModelData:getDimensions() end + +--- +---Returns the height of the model, computed from its axis-aligned bounding box. +--- +---@return number height # The height of the model. +function ModelData:getHeight() end + +--- +---Returns one of the Images in the model, by index. +--- +---@param index number # The index of the Image to get. +---@return lovr.Image image # The Image object. +function ModelData:getImage(index) end + +--- +---Returns the number of Images in the model. +--- +---@return number count # The number of Images in the model. +function ModelData:getImageCount() end + +--- +---Returns a table with all of the properties of a material. +--- +--- +---### NOTE: +---All images are optional and may be `nil`. +--- +---@overload fun(self: lovr.ModelData, name: string):table +---@param index number # The index of a material. +---@return {color: table, glow: table, uvShift: table, uvScale: table, metalness: number, roughness: number, clearcoat: number, clearcoatRoughness: number, occlusionStrength: number, normalScale: number, alphaCutoff: number, texture: number, glowTexture: number, occlusionTexture: number, metalnessTexture: number, roughnessTexture: number, clearcoatTexture: number, normalTexture: number} properties # The material properties. +function ModelData:getMaterial(index) end + +--- +---Returns the number of materials in the model. +--- +---@return number count # The number of materials in the model. +function ModelData:getMaterialCount() end + +--- +---Returns the name of a material in the model. +--- +---@param index number # The index of a material. +---@return string name # The name of the material, or nil if the material does not have a name. +function ModelData:getMaterialName(index) end + +--- +---Returns the number of meshes in the model. +--- +---@return number count # The number of meshes in the model. +function ModelData:getMeshCount() end + +--- +---Returns the draw mode of a mesh. +--- +---This controls how its vertices are connected together (points, lines, or triangles). +--- +---@param mesh number # The index of a mesh. +---@return lovr.DrawMode mode # The draw mode of the mesh. +function ModelData:getMeshDrawMode(mesh) end + +--- +---Returns one of the vertex indices in a mesh. +--- +---If a mesh has vertex indices, they define the order and connectivity of the vertices in the mesh, allowing a vertex to be reused multiple times without duplicating its data. +--- +---@param mesh number # The index of a mesh to get the vertex from. +---@param index number # The index of a vertex index in the mesh to retrieve. +---@return number vertexindex # The vertex index. Like all indices in Lua, this is 1-indexed. +function ModelData:getMeshIndex(mesh, index) end + +--- +---Returns the number of vertex indices in a mesh. +--- +---Vertex indices allow for vertices to be reused when defining triangles. +--- +--- +---### NOTE: +---This may return zero if the mesh does not use indices. +--- +---@param mesh number # The index of a mesh. +---@return number count # The number of vertex indices in the mesh. +function ModelData:getMeshIndexCount(mesh) end + +--- +---Returns the data format of vertex indices in a mesh. +--- +---If a mesh doesn't use vertex indices, this function returns nil. +--- +---@param mesh number # The index of a mesh. +---@return lovr.AttributeType type # The data type of each vertex index (always u16 or u32). +---@return number blob # The index of a Blob in the mesh where the binary data is stored. +---@return number offset # A byte offset into the Blob's data where the index data starts. +---@return number stride # The number of bytes between subsequent vertex indices. Indices are always tightly packed, so this will always be 2 or 4 depending on the data type. +function ModelData:getMeshIndexFormat(mesh) end + +--- +---Returns the index of the material applied to a mesh. +--- +---@param mesh number # The index of a mesh. +---@return number material # The index of the material applied to the mesh, or nil if the mesh does not have a material. +function ModelData:getMeshMaterial(mesh) end + +--- +---Returns the data for a single vertex in a mesh. +--- +---The data returned depends on the vertex format of a mesh, which is given by `ModelData:getMeshVertexFormat`. +--- +---@param mesh number # The index of a mesh to get the vertex from. +---@param vertex number # The index of a vertex in the mesh to retrieve. +function ModelData:getMeshVertex(mesh, vertex) end + +--- +---Returns the number of vertices in a mesh. +--- +---@param mesh number # The index of a mesh. +---@return number count # The number of vertices in the mesh. +function ModelData:getMeshVertexCount(mesh) end + +--- +---Returns the vertex format of a mesh. +--- +---The vertex format defines the properties associated with each vertex (position, color, etc.), including their types and binary data layout. +--- +--- +---### NOTE: +---The format is given as a table of vertex attributes. +--- +---Each attribute is a table containing the following: +--- +--- { name, type, components, blob, offset, stride } +--- +---- The `name` will be a `DefaultAttribute`. +---- The `type` will be an `AttributeType`. +---- The `component` count will be 1-4. +---- The `blob` is an index of one of the Blobs in the model (see `ModelData:getBlob`). +---- The `offset` is a byte offset from the start of the Blob where the attribute's data starts. +---- The `stride` is the number of bytes between consecutive values. +--- +---@param mesh number # The index of a mesh. +---@return table format # The vertex format of the mesh. +function ModelData:getMeshVertexFormat(mesh) end + +--- +---Returns extra information stored in the model file. +--- +---Currently this is only implemented for glTF models and returns the JSON string from the glTF or glb file. +--- +---The metadata can be used to get application-specific data or add support for glTF extensions not supported by LÖVR. +--- +---@return string metadata # The metadata from the model file. +function ModelData:getMetadata() end + +--- +---Given a parent node, this function returns a table with the indices of its children. +--- +--- +---### NOTE: +---If the node does not have any children, this function returns an empty table. +--- +---@overload fun(self: lovr.ModelData, name: string):table +---@param index number # The index of the parent node. +---@return table children # A table containing a node index for each child of the node. +function ModelData:getNodeChildren(index) end + +--- +---Returns the number of nodes in the model. +--- +---@return number count # The number of nodes in the model. +function ModelData:getNodeCount() end + +--- +---Returns a table of mesh indices attached to a node. +--- +---Meshes define the geometry and materials of a model, as opposed to the nodes which define the transforms and hierarchy. +--- +---A node can have multiple meshes, and meshes can be reused in multiple nodes. +--- +---@overload fun(self: lovr.ModelData, name: string):table +---@param index number # The index of the node. +---@return table meshes # A table with the node's mesh indices. +function ModelData:getNodeMeshes(index) end + +--- +---Returns the name of a node. +--- +--- +---### NOTE: +---If the node does not have a name, this function returns `nil`. +--- +---@param index number # The index of the node. +---@return string name # The name of the node. +function ModelData:getNodeName(index) end + +--- +---Returns local orientation of a node, relative to its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number, number, number, number +---@param index number # The index of the node. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function ModelData:getNodeOrientation(index) end + +--- +---Given a child node, this function returns the index of its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number +---@param index number # The index of the child node. +---@return number parent # The index of the parent. +function ModelData:getNodeParent(index) end + +--- +---Returns local pose (position and orientation) of a node, relative to its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number, number, number, number, number, number, number +---@param index number # The index of the node. +---@return number x # The x coordinate. +---@return number y # The y coordinate. +---@return number z # The z coordinate. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function ModelData:getNodePose(index) end + +--- +---Returns local position of a node, relative to its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number, number, number +---@param index number # The index of the node. +---@return number x # The x coordinate. +---@return number y # The y coordinate. +---@return number z # The z coordinate. +function ModelData:getNodePosition(index) end + +--- +---Returns local scale of a node, relative to its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number, number, number +---@param index number # The index of the node. +---@return number sx # The x scale. +---@return number sy # The y scale. +---@return number sz # The z scale. +function ModelData:getNodeScale(index) end + +--- +---Returns the index of the skin used by a node. +--- +---Skins are collections of joints used for skeletal animation. +--- +---A model can have multiple skins, and each node can use at most one skin to drive the animation of its meshes. +--- +---@overload fun(self: lovr.ModelData, name: string):number +---@param index number # The index of the node. +---@return number skin # The index of the node's skin, or nil if the node isn't skeletally animated. +function ModelData:getNodeSkin(index) end + +--- +---Returns local transform (position, orientation, and scale) of a node, relative to its parent. +--- +---@overload fun(self: lovr.ModelData, name: string):number, number, number, number, number, number, number, number, number, number +---@param index number # The index of the node. +---@return number x # The x coordinate. +---@return number y # The y coordinate. +---@return number z # The z coordinate. +---@return number sx # The x scale. +---@return number sy # The y scale. +---@return number sz # The z scale. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function ModelData:getNodeTransform(index) end + +--- +---Returns the index of the model's root node. +--- +---@return number root # The index of the root node. +function ModelData:getRootNode() end + +--- +---Returns the number of skins in the model. +--- +---A skin is a collection of joints targeted by an animation. +--- +--- +---### NOTE: +---There is currently a maximum of 256 skins. +--- +---@return number count # The number of skins in the model. +function ModelData:getSkinCount() end + +--- +---Returns the inverse bind matrix for a joint in the skin. +--- +---@param skin number # The index of a skin. +---@param joint number # The index of a joint in the skin. +function ModelData:getSkinInverseBindMatrix(skin, joint) end + +--- +---Returns a table with the node indices of the joints in a skin. +--- +---@param skin number # The index of a skin. +---@return table joints # The joints in the skin. +function ModelData:getSkinJoints(skin) end + +--- +---Returns the total number of triangles in the model. +--- +---This count includes meshes that are attached to multiple nodes, and the count corresponds to the triangles returned by `ModelData:getTriangles`. +--- +---@return number count # The total number of triangles in the model. +function ModelData:getTriangleCount() end + +--- +---Returns the data for all triangles in the model. +--- +---There are a few differences between this and the mesh-specific functions like `ModelData:getMeshVertex` and `ModelData:getMeshIndex`: +--- +---- Only vertex positions are returned, not other vertex attributes. +---- Positions are relative to the origin of the whole model, instead of local to a node. +---- If a mesh is attached to more than one node, its vertices will be in the table multiple times. +---- Vertex indices will be relative to the whole triangle list instead of a mesh. +--- +--- +---### NOTE: +---After this function is called on a ModelData once, the result is cached. +--- +---@return table vertices # The triangle vertex positions, returned as a flat (non-nested) table of numbers. The position of each vertex is given as an x, y, and z coordinate. +---@return table indices # The vertex indices. Every 3 indices describes a triangle. +function ModelData:getTriangles() end + +--- +---Returns the total vertex count of a model. +--- +---This count includes meshes that are attached to multiple nodes, and the count corresponds to the vertices returned by `ModelData:getTriangles`. +--- +---@return number count # The total number of vertices in the model. +function ModelData:getVertexCount() end + +--- +---Returns the width of the model, computed from its axis-aligned bounding box. +--- +---@return number width # The width of the model. +function ModelData:getWidth() end + +--- ---A Rasterizer is an object that parses a TTF file, decoding and rendering glyphs from it. --- ---Usually you can just use `Font` objects. @@ -534,6 +1020,56 @@ function Sound:isStream() end function Sound:setFrames(t, count, dstOffset, srcOffset) end --- +---This indicates the different transform properties that can be animated. +--- +---@alias lovr.AnimationProperty +--- +---Node translation. +--- +---| "translation" +--- +---Node rotation. +--- +---| "rotation" +--- +---Node scale. +--- +---| "scale" + +--- +---These are the data types that can be used by vertex data in meshes. +--- +---@alias lovr.AttributeType +--- +---Signed 8 bit integers (-128 to 127). +--- +---| "i8" +--- +---Unsigned 8 bit integers (0 to 255). +--- +---| "u8" +--- +---Signed 16 bit integers (-32768 to 32767). +--- +---| "i16" +--- +---Unsigned 16 bit integers (0 to 65535). +--- +---| "u16" +--- +---Signed 32 bit integers (-2147483648 to 2147483647). +--- +---| "i32" +--- +---Unsigned 32 bit integers (0 to 429467295). +--- +---| "u32" +--- +---Floating point numbers. +--- +---| "f32" + +--- ---Sounds can have different numbers of channels, and those channels can map to various speaker layouts. --- ---@alias lovr.ChannelLayout @@ -557,6 +1093,76 @@ function Sound:setFrames(t, count, dstOffset, srcOffset) end ---| "ambisonic" --- +---These are the different types of attributes that may be present in meshes loaded from models. +--- +---@alias lovr.DefaultAttribute +--- +---Vertex positions. +--- +---| "position" +--- +---Vertex normal vectors. +--- +---| "normal" +--- +---Vertex texture coordinates. +--- +---| "uv" +--- +---Vertex colors. +--- +---| "color" +--- +---Vertex tangent vectors. +--- +---| "tangent" +--- +---Vertex joint indices. +--- +---| "joints" +--- +---Vertex joint weights. +--- +---| "weights" + +--- +---The DrawMode of a mesh determines how its vertices are connected together. +--- +---@alias lovr.DrawMode +--- +---Each vertex is draw as a single point. +--- +---| "points" +--- +---Every pair of vertices is drawn as a line. +--- +---| "lines" +--- +---Draws a single line through all of the vertices. +--- +---| "linestrip" +--- +---Draws a single line through all of the vertices, then connects back to the first vertex. +--- +---| "lineloop" +--- +---Vertices are rendered as triangles. +--- +---After the first 3 vertices, each subsequent vertex connects to the previous two. +--- +---| "strip" +--- +---Every 3 vertices forms a triangle. +--- +---| "triangles" +--- +---Vertices are rendered as triangles. +--- +---After the first 3 vertices, each subsequent vertex is connected to the previous vertex and the first vertex. +--- +---| "fan" + +--- ---Sounds can store audio samples as 16 bit integers or 32 bit floats. --- ---@alias lovr.SampleFormat @@ -568,3 +1174,287 @@ function Sound:setFrames(t, count, dstOffset, srcOffset) end ---16 bit integer samples (between -32768 and 32767). --- ---| "i16" + +--- +---Different ways to interpolate between animation keyframes. +--- +---@alias lovr.SmoothMode +--- +---The animated property will snap to the nearest keyframe. +--- +---| "step" +--- +---The animated property will linearly interpolate between keyframes. +--- +---| "linear" +--- +---The animated property will follow a smooth curve between nearby keyframes. +--- +---| "cubic" + +--- +---Different data layouts for pixels in `Image` and `Texture` objects. +--- +---Formats starting with `d` are depth formats, used for depth/stencil render targets. +--- +---Formats starting with `bc` and `astc` are compressed formats. +--- +---Compressed formats have better performance since they stay compressed on the CPU and GPU, reducing the amount of memory bandwidth required to look up all the pixels needed for shading. +--- +---Formats without the `f` suffix are unsigned normalized formats, which store values in the range `[0,1]`. +--- +---The `f` suffix indicates a floating point format which can store values outside this range, and is used for HDR rendering or storing data in a texture. +--- +---@alias lovr.TextureFormat +--- +---One 8-bit channel. +--- +---1 byte per pixel. +--- +---| "r8" +--- +---Two 8-bit channels. +--- +---2 bytes per pixel. +--- +---| "rg8" +--- +---Four 8-bit channels. +--- +---4 bytes per pixel. +--- +---| "rgba8" +--- +---One 16-bit channel. +--- +---2 bytes per pixel. +--- +---| "r16" +--- +---Two 16-bit channels. +--- +---4 bytes per pixel. +--- +---| "rg16" +--- +---Four 16-bit channels. +--- +---8 bytes per pixel. +--- +---| "rgba16" +--- +---One 16-bit floating point channel. +--- +---2 bytes per pixel. +--- +---| "r16f" +--- +---Two 16-bit floating point channels. +--- +---4 bytes per pixel. +--- +---| "rg16f" +--- +---Four 16-bit floating point channels. +--- +---8 bytes per pixel. +--- +---| "rgba16f" +--- +---One 32-bit floating point channel. +--- +---4 bytes per pixel. +--- +---| "r32f" +--- +---Two 32-bit floating point channels. +--- +---8 bytes per pixel. +--- +---| "rg32f" +--- +---Four 32-bit floating point channels. +--- +---16 bytes per pixel. +--- +---| "rgba32f" +--- +---Packs three channels into 16 bits. +--- +---2 bytes per pixel. +--- +---| "rgb565" +--- +---Packs four channels into 16 bits, with "cutout" alpha. +--- +---2 bytes per pixel. +--- +---| "rgb5a1" +--- +---Packs four channels into 32 bits. +--- +---4 bytes per pixel. +--- +---| "rgb10a2" +--- +---Packs three unsigned floating point channels into 32 bits. +--- +---4 bytes per pixel. +--- +---| "rg11b10f" +--- +---One 16-bit depth channel. +--- +---2 bytes per pixel. +--- +---| "d16" +--- +---One 24-bit depth channel and one 8-bit stencil channel. +--- +---4 bytes per pixel. +--- +---| "d24s8" +--- +---One 32-bit floating point depth channel. +--- +---4 bytes per pixel. +--- +---| "d32f" +--- +---3 channels. +--- +---8 bytes per 4x4 block, or 0.5 bytes per pixel. +--- +---Good for opaque images. +--- +---| "bc1" +--- +---Four channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---Not good for anything, because it only has 16 distinct levels of alpha. +--- +---| "bc2" +--- +---Four channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---Good for color images with transparency. +--- +---| "bc3" +--- +---One unsigned normalized channel. +--- +---8 bytes per 4x4 block or 0.5 bytes per pixel. +--- +---Good for grayscale images, like heightmaps. +--- +---| "bc4u" +--- +---One signed normalized channel. +--- +---8 bytes per 4x4 block or 0.5 bytes per pixel. +--- +---Similar to bc4u but has a range of -1 to 1. +--- +---| "bc4s" +--- +---Two unsigned normalized channels. +--- +---16 bytes per 4x4 block, or 1 byte per pixel. +--- +---Good for normal maps. +--- +---| "bc5u" +--- +---Two signed normalized channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---Good for normal maps. +--- +---| "bc5s" +--- +---Three unsigned floating point channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---Good for HDR images. +--- +---| "bc6uf" +--- +---Three floating point channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---Good for HDR images. +--- +---| "bc6sf" +--- +---Four channels. +--- +---16 bytes per 4x4 block or 1 byte per pixel. +--- +---High quality. +--- +---Good for most color images, including transparency. +--- +---| "bc7" +--- +---Four channels, 16 bytes per 4x4 block or 1 byte per pixel. +--- +---| "astc4x4" +--- +---Four channels, 16 bytes per 5x4 block or 0.80 bytes per pixel. +--- +---| "astc5x4" +--- +---Four channels, 16 bytes per 5x5 block or 0.64 bytes per pixel. +--- +---| "astc5x5" +--- +---Four channels, 16 bytes per 6x5 block or 0.53 bytes per pixel. +--- +---| "astc6x5" +--- +---Four channels, 16 bytes per 6x6 block or 0.44 bytes per pixel. +--- +---| "astc6x6" +--- +---Four channels, 16 bytes per 8x5 block or 0.40 bytes per pixel. +--- +---| "astc8x5" +--- +---Four channels, 16 bytes per 8x6 block or 0.33 bytes per pixel. +--- +---| "astc8x6" +--- +---Four channels, 16 bytes per 8x8 block or 0.25 bytes per pixel. +--- +---| "astc8x8" +--- +---Four channels, 16 bytes per 10x5 block or 0.32 bytes per pixel. +--- +---| "astc10x5" +--- +---Four channels, 16 bytes per 10x6 block or 0.27 bytes per pixel. +--- +---| "astc10x6" +--- +---Four channels, 16 bytes per 10x8 block or 0.20 bytes per pixel. +--- +---| "astc10x8" +--- +---Four channels, 16 bytes per 10x10 block or 0.16 bytes per pixel. +--- +---| "astc10x10" +--- +---Four channels, 16 bytes per 12x10 block or 0.13 bytes per pixel. +--- +---| "astc12x10" +--- +---Four channels, 16 bytes per 12x12 block or 0.11 bytes per pixel. +--- +---| "astc12x12" diff --git a/meta/3rd/lovr/library/lovr/event.lua b/meta/3rd/lovr/library/lovr/event.lua index a515c1ab..3acc9cc6 100644 --- a/meta/3rd/lovr/library/lovr/event.lua +++ b/meta/3rd/lovr/library/lovr/event.lua @@ -48,8 +48,7 @@ function lovr.event.pump() end ---Only nil, booleans, numbers, strings, and LÖVR objects are supported types for event data. --- ---@param name string # The name of the event. ----@vararg any # The arguments for the event. Currently, up to 4 are supported. -function lovr.event.push(name, ...) end +function lovr.event.push(name) end --- ---Pushes an event to quit. diff --git a/meta/3rd/lovr/library/lovr/graphics.lua b/meta/3rd/lovr/library/lovr/graphics.lua index 88dd378b..5dd8f32b 100644 --- a/meta/3rd/lovr/library/lovr/graphics.lua +++ b/meta/3rd/lovr/library/lovr/graphics.lua @@ -1,3267 +1,2624 @@ ---@meta --- ----The `lovr.graphics` module renders graphics to displays. ---- ----Anything rendered using this module will automatically show up in the VR headset if one is connected, otherwise it will just show up in a window on the desktop. +---The graphics module renders graphics and performs computation using the GPU. --- ---@class lovr.graphics lovr.graphics = {} --- ----Draws an arc. ---- ---- ----### NOTE: ----The local normal vector of the circle is `(0, 0, 1)`. ---- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, radius?: number, angle?: number, ax?: number, ay?: number, az?: number, start?: number, end?: number, segments?: number) ----@overload fun(mode: lovr.DrawStyle, transform: lovr.mat4, start?: number, end?: number, segments?: number) ----@overload fun(material: lovr.Material, transform: lovr.mat4, start?: number, end?: number, segments?: number) ----@overload fun(mode: lovr.DrawStyle, arcmode?: lovr.ArcMode, x?: number, y?: number, z?: number, radius?: number, angle?: number, ax?: number, ay?: number, az?: number, start?: number, end?: number, segments?: number) ----@overload fun(material: lovr.Material, arcmode?: lovr.ArcMode, x?: number, y?: number, z?: number, radius?: number, angle?: number, ax?: number, ay?: number, az?: number, start?: number, end?: number, segments?: number) ----@overload fun(mode: lovr.DrawStyle, arcmode?: lovr.ArcMode, transform: lovr.mat4, start?: number, end?: number, segments?: number) ----@overload fun(material: lovr.Material, arcmode?: lovr.ArcMode, transform: lovr.mat4, start?: number, end?: number, segments?: number) ----@param mode lovr.DrawStyle # Whether the arc is filled or outlined. ----@param x? number # The x coordinate of the center of the arc. ----@param y? number # The y coordinate of the center of the arc. ----@param z? number # The z coordinate of the center of the arc. ----@param radius? number # The radius of the arc, in meters. ----@param angle? number # The rotation of the arc around its rotation axis, in radians. ----@param ax? number # The x coordinate of the arc's axis of rotation. ----@param ay? number # The y coordinate of the arc's axis of rotation. ----@param az? number # The z coordinate of the arc's axis of rotation. ----@param start? number # The starting angle of the arc, in radians. ----@param end? number # The ending angle of the arc, in radians. ----@param segments? number # The number of segments to use for the full circle. A smaller number of segments will be used, depending on how long the arc is. -function lovr.graphics.arc(mode, x, y, z, radius, angle, ax, ay, az, start, end, segments) end - ---- ----Draws a box. ---- ----This is similar to `lovr.graphics.cube` except you can have different values for the width, height, and depth of the box. +---TODO --- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, width?: number, height?: number, depth?: number, angle?: number, ax?: number, ay?: number, az?: number) ----@overload fun(mode: lovr.DrawStyle, transform: lovr.mat4) ----@overload fun(material: lovr.Material, transform: lovr.mat4) ----@param mode lovr.DrawStyle # How to draw the box. ----@param x? number # The x coordinate of the center of the box. ----@param y? number # The y coordinate of the center of the box. ----@param z? number # The z coordinate of the center of the box. ----@param width? number # The width of the box, in meters. ----@param height? number # The height of the box, in meters. ----@param depth? number # The depth of the box, in meters. ----@param angle? number # The rotation of the box around its rotation axis, in radians. ----@param ax? number # The x coordinate of the axis of rotation. ----@param ay? number # The y coordinate of the axis of rotation. ----@param az? number # The z coordinate of the axis of rotation. -function lovr.graphics.box(mode, x, y, z, width, height, depth, angle, ax, ay, az) end +---@param stage lovr.ShaderStage # TODO +---@param source lovr.ShaderSource # TODO +---@return lovr.Blob bytecode # TODO +function lovr.graphics.compileShader(stage, source) end --- ----Draws a 2D circle. +---TODO --- --- ---### NOTE: ----The local normal vector of the circle is `(0, 0, 1)`. +---TODO --- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, radius?: number, angle?: number, ax?: number, ay?: number, az?: number, segments?: number) ----@overload fun(mode: lovr.DrawStyle, transform: lovr.mat4, segments?: number) ----@overload fun(material: lovr.Material, transform: lovr.mat4, segments?: number) ----@param mode lovr.DrawStyle # Whether the circle is filled or outlined. ----@param x? number # The x coordinate of the center of the circle. ----@param y? number # The y coordinate of the center of the circle. ----@param z? number # The z coordinate of the center of the circle. ----@param radius? number # The radius of the circle, in meters. ----@param angle? number # The rotation of the circle around its rotation axis, in radians. ----@param ax? number # The x coordinate of the circle's axis of rotation. ----@param ay? number # The y coordinate of the circle's axis of rotation. ----@param az? number # The z coordinate of the circle's axis of rotation. ----@param segments? number # The number of segments to use for the circle geometry. Higher numbers increase smoothness but increase rendering cost slightly. -function lovr.graphics.circle(mode, x, y, z, radius, angle, ax, ay, az, segments) end +---@return number r # The red component of the background color. +---@return number g # The green component of the background color. +---@return number b # The blue component of the background color. +---@return number a # The alpha component of the background color. +function lovr.graphics.getBackgroundColor() end --- ----Clears the screen, resetting the color, depth, and stencil information to default values. ---- ----This function is called automatically by `lovr.run` at the beginning of each frame to clear out the data from the previous frame. +---Creates a temporary Buffer. --- --- ---### NOTE: ----The first two variants of this function can be mixed and matched, meaning you can use booleans for some of the values and numeric values for others. +---The format table can contain a list of `FieldType`s or a list of tables to provide extra information about each field. --- ----If you are using `lovr.graphics.setStencilTest`, it will not affect how the screen gets cleared. Instead, you can use `lovr.graphics.fill` to draw a fullscreen quad, which will get masked by the active stencil. +---Each inner table has the following keys: --- ----@overload fun(r: number, g: number, b: number, a: number, z?: number, s?: number) ----@overload fun(hex: number) ----@param color? boolean # Whether or not to clear color information on the screen. ----@param depth? boolean # Whether or not to clear the depth information on the screen. ----@param stencil? boolean # Whether or not to clear the stencil information on the screen. -function lovr.graphics.clear(color, depth, stencil) end - +---- `type` is the `FieldType` of the field and is required. +---- `offset` is the byte offset of the field. --- ----This function runs a compute shader on the GPU. +---Any fields with a `nil` offset will be placed next +--- to each other sequentially in memory, subject to any padding required by the Buffer's layout. +--- In practice this means that you probably want to provide an `offset` for either all of the +--- fields or none of them. +---- `location` is the vertex attribute location of each field. --- ----Compute shaders must be created with `lovr.graphics.newComputeShader` and they should implement the `void compute();` GLSL function. Running a compute shader doesn't actually do anything, but the Shader can modify data stored in `Texture`s or `ShaderBlock`s to get interesting things to happen. +---This is used to match up each +--- field with an attribute declared in a shader, and doesn't have any purpose when binding the +--- buffer as a uniform or storage buffer. --- ----When running the compute shader, you can specify the number of times to run it in 3 dimensions, which is useful to iterate over large numbers of elements like pixels or array elements. +---Any fields with a `nil` location will use an +--- autoincrementing location starting at zero. --- +---Named locations are not currently supported, but +--- may be added in the future. --- ----### NOTE: ----Only compute shaders created with `lovr.graphics.newComputeShader` can be used here. +---If no table or Blob is used to define the initial Buffer contents, its data will be undefined. --- ----There are GPU-specific limits on the `x`, `y`, and `z` values which can be queried in the `compute` entry of `lovr.graphics.getLimits`. +---There is currently a max of 16 fields. --- ----@param shader lovr.Shader # The compute shader to run. ----@param x? number # The amount of times to run in the x direction. ----@param y? number # The amount of times to run in the y direction. ----@param z? number # The amount of times to run in the z direction. -function lovr.graphics.compute(shader, x, y, z) end +---@overload fun(data: table, type: lovr.FieldType):lovr.Buffer +---@overload fun(length: number, format: table):lovr.Buffer +---@overload fun(data: table, format: table):lovr.Buffer +---@overload fun(blob: lovr.Blob, type: lovr.FieldType):lovr.Buffer +---@overload fun(blob: lovr.Blob, format: table):lovr.Buffer +---@param length number # The length of the Buffer. +---@param type lovr.FieldType # The type of each item in the Buffer. +---@return lovr.Buffer buffer # The new Buffer. +function lovr.graphics.getBuffer(length, type) end --- ----Create the desktop window, usually used to mirror the headset display. +---Returns the default Font. --- +---The default font is Varela Round, created at 32px with a spread value of `4.0`. --- ----### NOTE: ----This function can only be called once. ---- ----It is normally called internally, but you can override this by setting window to `nil` in conf.lua. ---- ----See `lovr.conf` for more information. ---- ----The window must be created before any `lovr.graphics` functions can be used. +---It's used by `Pass:text` if no Font is provided. --- ----@param flags? {width: number, height: number, fullscreen: boolean, resizable: boolean, msaa: number, title: string, icon: string, vsync: number} # Flags to customize the window's appearance and behavior. -function lovr.graphics.createWindow(flags) end +---@return lovr.Font font # The default Font object. +function lovr.graphics.getDefaultFont() end --- ----Draws a cube. ---- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, size?: number, angle?: number, ax?: number, ay?: number, az?: number) ----@overload fun(mode: lovr.DrawStyle, transform: lovr.mat4) ----@overload fun(material: lovr.Material, transform: lovr.mat4) ----@param mode lovr.DrawStyle # How to draw the cube. ----@param x? number # The x coordinate of the center of the cube. ----@param y? number # The y coordinate of the center of the cube. ----@param z? number # The z coordinate of the center of the cube. ----@param size? number # The size of the cube, in meters. ----@param angle? number # The rotation of the cube around its rotation axis, in radians. ----@param ax? number # The x coordinate of the cube's axis of rotation. ----@param ay? number # The y coordinate of the cube's axis of rotation. ----@param az? number # The z coordinate of the cube's axis of rotation. -function lovr.graphics.cube(mode, x, y, z, size, angle, ax, ay, az) end - ---- ----Draws a cylinder. +---Returns information about the graphics device and driver. --- --- ---### NOTE: ----Currently, cylinders don't have UVs. +---The device and vendor ID numbers will usually be PCI IDs, which are standardized numbers consisting of 4 hex digits. --- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, length?: number, angle?: number, ax?: number, ay?: number, az?: number, r1?: number, r2?: number, capped?: boolean, segments?: number) ----@param x? number # The x coordinate of the center of the cylinder. ----@param y? number # The y coordinate of the center of the cylinder. ----@param z? number # The z coordinate of the center of the cylinder. ----@param length? number # The length of the cylinder, in meters. ----@param angle? number # The rotation of the cylinder around its rotation axis, in radians. ----@param ax? number # The x coordinate of the cylinder's axis of rotation. ----@param ay? number # The y coordinate of the cylinder's axis of rotation. ----@param az? number # The z coordinate of the cylinder's axis of rotation. ----@param r1? number # The radius of one end of the cylinder. ----@param r2? number # The radius of the other end of the cylinder. ----@param capped? boolean # Whether the top and bottom should be rendered. ----@param segments? number # The number of radial segments to use for the cylinder. If nil, the segment count is automatically determined from the radii. -function lovr.graphics.cylinder(x, y, z, length, angle, ax, ay, az, r1, r2, capped, segments) end - +---Various online databases and system utilities can be used to look up these numbers. --- ----Discards pixel information in the active Canvas or display. +---Here are some example vendor IDs for a few popular GPU manufacturers: --- ----This is mostly used as an optimization hint for the GPU, and is usually most helpful on mobile devices. ---- ----@param color? boolean # Whether or not to discard color information. ----@param depth? boolean # Whether or not to discard depth information. ----@param stencil? boolean # Whether or not to discard stencil information. -function lovr.graphics.discard(color, depth, stencil) end - +---<table> +--- <thead> +--- <tr> +--- <td>ID</td> +--- <td>Vendor</td> +--- </tr> +--- </thead> +--- <tbody> +--- <tr> +--- <td><code>0x1002</code></td> +--- <td>Advanced Micro Devices, Inc.</td> +--- </tr> +--- <tr> +--- <td><code>0x8086</code></td> +--- <td>Intel Corporation</td> +--- </tr> +--- <tr> +--- <td><code>0x10de</code></td> +--- <td>NVIDIA Corporation</td> +--- </tr> +--- </tbody> </table> --- ----Draws a fullscreen textured quad. +---It is not currently possible to get the version of the driver, although this could be added. --- +---Regarding multiple GPUs: If OpenXR is enabled, the OpenXR runtime has control over which GPU is used, which ensures best compatibility with the VR headset. --- ----### NOTE: ----This function ignores stereo rendering, so it will stretch the input across the entire Canvas if it's stereo. +---Otherwise, the "first" GPU returned by the renderer will be used. --- ----Special shaders are currently required for correct stereo fills. +---There is currently no other way to pick a GPU to use. --- ----@overload fun() ----@param texture lovr.Texture # The texture to use. ----@param u? number # The x component of the uv offset. ----@param v? number # The y component of the uv offset. ----@param w? number # The width of the Texture to render, in uv coordinates. ----@param h? number # The height of the Texture to render, in uv coordinates. -function lovr.graphics.fill(texture, u, v, w, h) end +---@return {id: number, vendor: number, name: string, renderer: string, subgroupSize: number, discrete: boolean} device # nil +function lovr.graphics.getDevice() end --- ----Flushes the internal queue of draw batches. ---- ----Under normal circumstances this is done automatically when needed, but the ability to flush manually may be helpful if you're integrating a LÖVR project with some external rendering code. +---Returns a table indicating which features are supported by the GPU. --- -function lovr.graphics.flush() end +---@return {textureBC: boolean, textureASTC: boolean, wireframe: boolean, depthClamp: boolean, indirectDrawFirstInstance: boolean, float64: boolean, int64: boolean, int16: boolean} features # +function lovr.graphics.getFeatures() end --- ----Returns whether or not alpha sampling is enabled. ---- ----Alpha sampling is also known as alpha-to-coverage. ---- ----When it is enabled, the alpha channel of a pixel is factored into how antialiasing is computed, so the edges of a transparent texture will be correctly antialiased. +---Returns limits of the current GPU. --- --- ---### NOTE: ----- Alpha sampling is disabled by default. ----- This feature can be used for a simple transparency effect, pixels with an alpha of zero will ---- have their depth value discarded, allowing things behind them to show through (normally you ---- have to sort objects or write a shader for this). ---- ----@return boolean enabled # Whether or not alpha sampling is enabled. -function lovr.graphics.getAlphaSampling() end - ---- ----Returns the current background color. ---- ----Color components are from 0.0 to 1.0. +---The limit ranges are as follows: --- +---<table> +--- <thead> +--- <tr> +--- <td>Limit</td> +--- <td>Minimum</td> +--- <td>Maximum</td> +--- </tr> +--- </thead> +--- <tbody> +--- <tr> +--- <td><code>textureSize2D</code></td> +--- <td>4096</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>textureSize3D</code></td> +--- <td>256</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>textureSizeCube</code></td> +--- <td>4096</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>textureLayers</code></td> +--- <td>256</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>renderSize</code></td> +--- <td>{ 4096, 4096, 6 }</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>uniformBuffersPerStage</code></td> +--- <td>9</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>storageBuffersPerStage</code></td> +--- <td>4</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>sampledTexturesPerStage</code></td> +--- <td>32</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>storageTexturesPerStage</code></td> +--- <td>4</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>samplersPerStage</code></td> +--- <td>15</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>resourcesPerShader</code></td> +--- <td>32</td> +--- <td>32*</td> +--- </tr> +--- <tr> +--- <td><code>uniformBufferRange</code></td> +--- <td>65536</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>storageBufferRange</code></td> +--- <td>134217728 (128MB)</td> +--- <td>1073741824 (1GB)*</td> +--- </tr> +--- <tr> +--- <td><code>uniformBufferAlign</code></td> +--- <td></td> +--- <td>256</td> +--- </tr> +--- <tr> +--- <td><code>storageBufferAlign</code></td> +--- <td></td> +--- <td>64</td> +--- </tr> +--- <tr> +--- <td><code>vertexAttributes</code></td> +--- <td>16</td> +--- <td>16*</td> +--- </tr> +--- <tr> +--- <td><code>vertexBufferStride</code></td> +--- <td>2048</td> +--- <td>65535*</td> +--- </tr> +--- <tr> +--- <td><code>vertexShaderOutputs</code></td> +--- <td>64</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>clipDistances</code></td> +--- <td>0</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>cullDistances</code></td> +--- <td>0</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>clipAndCullDistances</code></td> +--- <td>0</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>computeDispatchCount</code></td> +--- <td>{ 65536, 65536, 65536 }</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>computeWorkgroupSize</code></td> +--- <td>{ 128, 128, 64 }</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>computeWorkgroupVolume</code></td> +--- <td>128</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>computeSharedMemory</code></td> +--- <td>16384 (16KB)</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>pushConstantSize</code></td> +--- <td>128</td> +--- <td>256*</td> +--- </tr> +--- <tr> +--- <td><code>indirectDrawCount</code></td> +--- <td>1</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>instances</code></td> +--- <td>134217727</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>anisotropy</code></td> +--- <td>0.0</td> +--- <td></td> +--- </tr> +--- <tr> +--- <td><code>pointSize</code></td> +--- <td>1.0</td> +--- <td></td> +--- </tr> +--- </tbody> </table> --- ----### NOTE: ----The default background color is `(0.0, 0.0, 0.0, 1.0)`. +---Note: in the table above, `*` means that LÖVR itself is imposing a cap on the limit, instead of the GPU. --- ----@return number r # The red component of the background color. ----@return number g # The green component of the background color. ----@return number b # The blue component of the background color. ----@return number a # The alpha component of the background color. -function lovr.graphics.getBackgroundColor() end +---@return {textureSize2D: number, textureSize3D: number, textureSizeCube: number, textureLayers: number, renderSize: table, uniformBuffersPerStage: number, storageBuffersPerStage: number, sampledTexturesPerStage: number, storageTexturesPerStage: number, samplersPerStage: number, resourcesPerShader: number, uniformBufferRange: number, storageBufferRange: number, uniformBufferAlign: number, storageBufferAlign: number, vertexAttributes: number, vertexBufferStride: number, vertexShaderOutputs: number, clipDistances: number, cullDistances: number, clipAndCullDistances: number, workgroupCount: table, workgroupSize: table, totalWorkgroupSize: number, computeSharedMemory: number, shaderConstantSize: number, indirectDrawCount: number, instances: number, anisotropy: number, pointSize: number} limits # +function lovr.graphics.getLimits() end --- ----Returns the current blend mode. ---- ----The blend mode controls how each pixel's color is blended with the previous pixel's color when drawn. ---- ----If blending is disabled, `nil` will be returned. ---- +---TODO --- ----### NOTE: ----The default blend mode is `alpha` and `alphamultiply`. ---- ----@return lovr.BlendMode blend # The current blend mode. ----@return lovr.BlendAlphaMode alphaBlend # The current alpha blend mode. -function lovr.graphics.getBlendMode() end +---@overload fun(type: lovr.PassType, texture: lovr.Texture):lovr.Pass +---@overload fun(type: lovr.PassType, canvas: table):lovr.Pass +---@param type lovr.PassType # TODO +---@return lovr.Pass pass # The new Pass. +function lovr.graphics.getPass(type) end --- ----Returns the active Canvas. ---- ----Usually when you render something it will render directly to the headset. ---- ----If a Canvas object is active, things will be rendered to the textures attached to the Canvas instead. +---TODO --- ----@return lovr.Canvas canvas # The active Canvas, or `nil` if no canvas is set. -function lovr.graphics.getCanvas() end +---@return {memory: {total: number, buffer: number, texture: number}, objects: {buffers: number, textures: number, samplers: number, shaders: number}, frame: {scratchMemory: number, renderPasses: number, computePasses: number, transferPasses: number, pipelineBinds: number, bundleBinds: number, drawCalls: number, dispatches: number, workgroups: number, copies: number}, internal: {blocks: number, canvases: number, pipelines: number, layouts: number, bunches: number}} stats # Graphics statistics. +function lovr.graphics.getStats() end --- ----Returns the current global color factor. +---Returns the window pass. --- ----Color components are from 0.0 to 1.0. +---This is a builtin render `Pass` object that renders to the desktop window texture. --- ----Every pixel drawn will be multiplied (i.e. tinted) by this color. +---If the desktop window was not open when the graphics module was initialized, this function will return `nil`. --- --- ---### NOTE: ----The default color is `(1.0, 1.0, 1.0, 1.0)`. +---- TODO is the same pass always returned +---- TODO does the texture change +---- TODO what settings does the Pass use (incl conf.lua) +---- TODO is it reset --- ----@return number r # The red component of the color. ----@return number g # The green component of the color. ----@return number b # The blue component of the color. ----@return number a # The alpha component of the color. -function lovr.graphics.getColor() end +---@return lovr.Pass pass # The window pass, or `nil` if there is no window. +function lovr.graphics.getWindowPass() end --- ----Returns a boolean for each color channel (red, green, blue, alpha) indicating whether it is enabled. ---- ----When a color channel is enabled, it will be affected by drawing commands and clear commands. +---TODO --- ---- ----### NOTE: ----By default, all color channels are enabled. ---- ----Disabling all of the color channels can be useful if you only want to write to the depth buffer or the stencil buffer. ---- -function lovr.graphics.getColorMask() end +---@param format lovr.TextureFormat # TODO +---@return boolean supported # TODO +function lovr.graphics.isFormatSupported(format) end --- ----Returns the default filter mode for new Textures. ---- ----This controls how textures are sampled when they are minified, magnified, or stretched. +---Creates a Buffer. --- --- ---### NOTE: ----The default filter is `trilinear`. +---The format table can contain a list of `FieldType`s or a list of tables to provide extra information about each field. --- ----@return lovr.FilterMode mode # The filter mode. ----@return number anisotropy # The level of anisotropy. -function lovr.graphics.getDefaultFilter() end - ---- ----Returns the current depth test settings. +---Each inner table has the following keys: --- +---- `type` is the `FieldType` of the field and is required. +---- `offset` is the byte offset of the field. --- ----### NOTE: ----The depth test is an advanced technique to control how 3D objects overlap each other when they are rendered. ---- ----It works as follows: +---Any fields with a `nil` offset will be placed next +--- to each other sequentially in memory, subject to any padding required by the Buffer's layout. +--- In practice this means that you probably want to provide an `offset` for either all of the +--- fields or none of them. +---- `location` is the vertex attribute location of each field. --- ----- Each pixel keeps track of its z value as well as its color. ----- If `write` is enabled when something is drawn, then any pixels that are drawn will have their ---- z values updated. ----- Additionally, anything drawn will first compare the existing z value of a pixel with the new z ---- value. +---This is used to match up each +--- field with an attribute declared in a shader, and doesn't have any purpose when binding the +--- buffer as a uniform or storage buffer. --- ----The `compareMode` setting determines how this comparison is performed. +---Any fields with a `nil` location will use an +--- autoincrementing location starting at zero. --- ----If the ---- comparison succeeds, the new pixel will overwrite the previous one, otherwise that pixel won't ---- be rendered to. +---Named locations are not currently supported, but +--- may be added in the future. --- ----Smaller z values are closer to the camera. +---If no table or Blob is used to define the initial Buffer contents, its data will be undefined. --- ----The default compare mode is `lequal`, which usually gives good results for normal 3D rendering. +---There is currently a max of 16 fields. --- ----@return lovr.CompareMode compareMode # The current comparison method for depth testing. ----@return boolean write # Whether pixels will have their z value updated when rendered to. -function lovr.graphics.getDepthTest() end +---@overload fun(data: table, type: lovr.FieldType):lovr.Buffer +---@overload fun(length: number, format: table):lovr.Buffer +---@overload fun(data: table, format: table):lovr.Buffer +---@overload fun(blob: lovr.Blob, type: lovr.FieldType):lovr.Buffer +---@overload fun(blob: lovr.Blob, format: table):lovr.Buffer +---@param length number # The length of the Buffer. +---@param type lovr.FieldType # The type of each item in the Buffer. +---@return lovr.Buffer buffer # The new Buffer. +function lovr.graphics.newBuffer(length, type) end --- ----Returns the dimensions of the desktop window. +---TODO --- ----@return number width # The width of the window, in pixels. ----@return number height # The height of the window, in pixels. -function lovr.graphics.getDimensions() end +---@overload fun(blob: lovr.Blob, size?: number, spread?: number):lovr.Font +---@overload fun(size?: number, spread?: number):lovr.Font +---@overload fun(rasterizer: lovr.Rasterizer, spread?: number):lovr.Font +---@param filename string # TODO +---@param size? number # TODO +---@param spread? number # TODO +---@return lovr.Font font # The new Font. +function lovr.graphics.newFont(filename, size, spread) end --- ----Returns whether certain features are supported by the system\'s graphics card. +---TODO --- ----@return {astc: boolean, compute: boolean, dxt: boolean, instancedstereo: boolean, multiview: boolean, timers: boolean} features # A table of features and whether or not they are supported. -function lovr.graphics.getFeatures() end +---@overload fun(options: table):lovr.Material +---@param texture lovr.Texture # TODO +---@return lovr.Material material # TODO +function lovr.graphics.newMaterial(texture) end --- ----Returns the active font. +---TODO --- ----@return lovr.Font font # The active font object. -function lovr.graphics.getFont() end +---@overload fun(blob: lovr.Blob, options: table):lovr.Model +---@overload fun(modelData: lovr.ModelData):lovr.Model +---@param filename string # TODO +---@param options {mipmaps: boolean} # Model options. +---@return lovr.Model model # The new Model. +function lovr.graphics.newModel(filename, options) end --- ----Returns the height of the desktop window. +---TODO --- ----@return number height # The height of the window, in pixels. -function lovr.graphics.getHeight() end +---@param options {filter: table, wrap: table, compare: lovr.CompareMode, anisotropy: number, mipmaprange: table} # TODO +---@return lovr.Sampler sampler # TODO +function lovr.graphics.newSampler(options) end --- ----Returns information about the maximum limits of the graphics card, such as the maximum texture size or the amount of supported antialiasing. +---TODO --- ----@return {anisotropy: number, blocksize: number, pointsize: number, texturemsaa: number, texturesize: number, compute: table} limits # The table of limits. -function lovr.graphics.getLimits() end +---@overload fun(compute: lovr.ShaderSource, options: table):lovr.Shader +---@param vertex lovr.ShaderSource # TODO +---@param fragment lovr.ShaderSource # TODO +---@param options {flags: table, label: string} # Shader options. +---@return lovr.Shader shader # TODO +function lovr.graphics.newShader(vertex, fragment, options) end --- ----Returns the current line width. +---TODO --- ---- ----### NOTE: ----The default line width is `1`. ---- ----@return number width # The current line width, in pixels. -function lovr.graphics.getLineWidth() end +---@param type lovr.TallyType # The type of the Tally, which controls what "thing" it measures. +---@param count number # The number of slots in the Tally. Each slot performs one measurement. +---@param views? number # Tally objects with the `time` type can only be used in render passes with a certain number of views. This is ignored for other types of tallies. +---@return lovr.Tally tally # The new Tally. +function lovr.graphics.newTally(type, count, views) end --- ----Returns the pixel density of the window. ---- ----On "high-dpi" displays, this will be `2.0`, indicating that there are 2 pixels for every window coordinate. ---- ----On a normal display it will be `1.0`, meaning that the pixel to window-coordinate ratio is 1:1. +---TODO --- ---- ----### NOTE: ----If the window isn't created yet, this function will return 0. ---- ----@return number density # The pixel density of the window. -function lovr.graphics.getPixelDensity() end +---@overload fun(width: number, height: number, options: table):lovr.Texture +---@overload fun(width: number, height: number, depth: number, options: table):lovr.Texture +---@overload fun(image: string, options: table):lovr.Texture +---@overload fun(images: table, options: table):lovr.Texture +---@param filename string # TODO +---@param options {type: lovr.TextureType, format: lovr.TextureFormat, linear: boolean, samples: number, mipmaps: number, usage: table, label: string} # Texture options. +---@return lovr.Texture texture # TODO +function lovr.graphics.newTexture(filename, options) end --- ----Returns the current point size. ---- +---Presents the window texture to the desktop window. --- ----### NOTE: ----The default point size is `1.0`. ---- ----@return number size # The current point size, in pixels. -function lovr.graphics.getPointSize() end - ---- ----Returns the projection for a single view. +---This function is called automatically by the default implementation of `lovr.run`, so it normally does not need to be called. --- --- ---### NOTE: ----Non-stereo rendering will only use the first view. ---- ----The projection matrices are available as the `mat4 lovrProjections[2]` variable in shaders. ---- ----The current projection matrix is available as `lovrProjection`. ---- ----@overload fun(view: number, matrix: lovr.Mat4):lovr.Mat4 ----@param view number # The view index. ----@return number left # The left field of view angle, in radians. ----@return number right # The right field of view angle, in radians. ----@return number up # The top field of view angle, in radians. ----@return number down # The bottom field of view angle, in radians. -function lovr.graphics.getProjection(view) end - ---- ----Returns the active shader. +---This should be called after submitting the window pass (`lovr.graphics.getWindowPass`). --- ----@return lovr.Shader shader # The active shader object, or `nil` if none is active. -function lovr.graphics.getShader() end - ---- ----Returns graphics-related performance statistics for the current frame. +---If the window texture has not been rendered to since the last present, this function does nothing. --- ----@return {drawcalls: number, renderpasses: number, shaderswitches: number, buffers: number, textures: number, buffermemory: number, texturememory: number} stats # The table of stats. -function lovr.graphics.getStats() end +function lovr.graphics.present() end --- ----Returns the current stencil test. ---- ----The stencil test lets you mask out pixels that meet certain criteria, based on the contents of the stencil buffer. ---- ----The stencil buffer can be modified using `lovr.graphics.stencil`. ---- ----After rendering to the stencil buffer, the stencil test can be set to control how subsequent drawing functions are masked by the stencil buffer. +---TODO --- --- ---### NOTE: ----Stencil values are between 0 and 255. ---- ----By default, the stencil test is disabled. ---- ----@return lovr.CompareMode compareMode # The comparison method used to decide if a pixel should be visible, or nil if the stencil test is disabled. ----@return number compareValue # The value stencil values are compared against, or nil if the stencil test is disabled. -function lovr.graphics.getStencilTest() end - ---- ----Get the pose of a single view. +---TODO --- ----@overload fun(view: number, matrix: lovr.Mat4, invert: boolean):lovr.Mat4 ----@param view number # The view index. ----@return number x # The x position of the viewer, in meters. ----@return number y # The y position of the viewer, in meters. ----@return number z # The z position of the viewer, in meters. ----@return number angle # The number of radians the viewer is rotated around its axis of rotation. ----@return number ax # The x component of the axis of rotation. ----@return number ay # The y component of the axis of rotation. ----@return number az # The z component of the axis of rotation. -function lovr.graphics.getViewPose(view) end +---@overload fun(hex: number, a?: number) +---@overload fun(color: table) +---@param r number # The red component of the background color. +---@param g number # The green component of the background color. +---@param b number # The blue component of the background color. +---@param a? number # The alpha component of the background color. +function lovr.graphics.setBackgroundColor(r, g, b, a) end --- ----Returns the width of the desktop window. +---TODO --- ----@return number width # The width of the window, in pixels. -function lovr.graphics.getWidth() end +---@overload fun(t: table):boolean +---@vararg lovr.Pass # The pass objects to submit. Falsy values will be skipped. +---@return boolean true # Always returns true, for convenience when returning from `lovr.draw`. +function lovr.graphics.submit(...) end --- ----Returns the current polygon winding. ---- ----The winding direction determines which face of a triangle is the front face and which is the back face. ---- ----This lets the graphics engine cull the back faces of polygons, improving performance. ---- +---TODO --- ----### NOTE: ----Culling is initially disabled and must be enabled using `lovr.graphics.setCullingEnabled`. ---- ----The default winding direction is counterclockwise. ---- ----@return lovr.Winding winding # The current winding direction. -function lovr.graphics.getWinding() end +function lovr.graphics.wait() end --- ----Returns whether the desktop window is currently created. +---A Buffer is a block of GPU memory. --- +---Buffers are similar to Lua tables or arrays: they have a length and store a list of values. --- ----### NOTE: ----Most of the `lovr.graphics` functionality will only work if a window is created. +---The length of a Buffer and its format (the type of each value) are declared upfront and can't be changed. --- ----@return boolean present # Whether a window is created. -function lovr.graphics.hasWindow() end - +---Each value of a Buffer consists of one or more fields, and each field has a type. --- ----Returns whether or not culling is active. +---For example, if a Buffer is used to store vertices, each value might store 3 fields for the position, normal vector, and UV coordinates of a vertex. --- ----Culling is an optimization that avoids rendering the back face of polygons. +---Buffers are commonly used for: --- ----This improves performance by reducing the number of polygons drawn, but requires that the vertices in triangles are specified in a consistent clockwise or counter clockwise order. +---- Mesh data: Buffers hold the data that define the vertices in a mesh. Buffers also store the +--- vertex indices of a mesh, which define the order the vertices are connected together into +--- triangles. These are often called vertex buffers and index buffers. +---- Shader data: Buffers can be bound to a Shader, letting the Shader read arbitrary data. For +--- example, Lua code could create a Buffer with the positions and colors of all the lights in a +--- scene, which a Shader can use to do lighting calculations. +---- Compute: Compute shaders can write data to Buffers. --- +---This GPU-generated data can be used in +--- later rendering work or sent back to Lua. +---- Indirect: Indirect rendering is an advanced technique where instructions for rendering work +--- are recorded to a Buffer (potentially by a compute shader) and later drawn. --- ----### NOTE: ----Culling is disabled by default. +---There are two types of Buffers: --- ----@return boolean isEnabled # Whether or not culling is enabled. -function lovr.graphics.isCullingEnabled() end - +---- **Temporary** buffers are very inexpensive to create, and writing to them from Lua is fast. +--- However, they become invalid at the end of `lovr.draw` (i.e. when `lovr.graphics.submit` is +--- called). --- ----Returns a boolean indicating whether or not wireframe rendering is enabled. +---The GPU is slightly slower at accessing data from temporary buffers, and compute +--- shaders can not write to them. --- +---They are designed for storing data that changes every frame. +---- **Permanent** buffers are more expensive to create, and updating their contents requires a +--- transfer from CPU memory to VRAM. --- ----### NOTE: ----Wireframe rendering is initially disabled. ---- ----Wireframe rendering is only supported on desktop systems. ---- ----@return boolean isWireframe # Whether or not wireframe rendering is enabled. -function lovr.graphics.isWireframe() end - +---They act like normal LÖVR objects and don't need to be +--- recreated every frame. --- ----Draws lines between points. +---They often have faster performance when used by the GPU, and compute +--- shaders can write to them. --- ----Each point will be connected to the previous point in the list. +---They are great for large pieces of data that are initialized once +--- at load time, or data that is updated infrequently. --- ----@overload fun(points: table) ----@param x1 number # The x coordinate of the first point. ----@param y1 number # The y coordinate of the first point. ----@param z1 number # The z coordinate of the first point. ----@param x2 number # The x coordinate of the second point. ----@param y2 number # The y coordinate of the second point. ----@param z2 number # The z coordinate of the second point. ----@vararg number # More points. -function lovr.graphics.line(x1, y1, z1, x2, y2, z2, ...) end +---@class lovr.Buffer +local Buffer = {} --- ----Creates a new Canvas. +---Clears some or all of the data in the Buffer to zero. --- ----You can specify Textures to attach to it, or just specify a width and height and attach textures later using `Canvas:setTexture`. +---This is supported for both temporary and permanent Buffers. --- ----Once created, you can render to the Canvas using `Canvas:renderTo`, or `lovr.graphics.setCanvas`. +---Permanent Buffers can also be cleared in a transfer pass using `Pass:clear`. --- --- ---### NOTE: ----Textures created by this function will have `clamp` as their `WrapMode`. +---Clearing a permanent buffer requires the byte offset and byte count of the cleared range to be a multiple of 4. --- ----Stereo Canvases will either have their width doubled or use array textures for their attachments, depending on their implementation. +---This will usually be true for most field types. --- ----@overload fun(..., flags?: table):lovr.Canvas ----@overload fun(attachments: table, flags?: table):lovr.Canvas ----@param width number # The width of the canvas, in pixels. ----@param height number # The height of the canvas, in pixels. ----@param flags? {format: lovr.TextureFormat, depth: lovr.TextureFormat, stereo: boolean, msaa: number, mipmaps: boolean} # Optional settings for the Canvas. ----@return lovr.Canvas canvas # The new Canvas. -function lovr.graphics.newCanvas(width, height, flags) end +---@param index? number # The index of the first item to clear. +---@param count? number # The number of items to clear. If `nil`, clears as many items as possible. +function Buffer:clear(index, count) end --- ----Creates a new compute Shader, used for running generic compute operations on the GPU. ---- +---Returns the format of the Buffer. --- ----### NOTE: ----Compute shaders are not supported on all hardware, use `lovr.graphics.getFeatures` to check if they're available on the current system. ---- ----The source code for a compute shader needs to implement the `void compute();` GLSL function. This function doesn't return anything, but the compute shader is able to write data out to `Texture`s or `ShaderBlock`s. +---This is the list of fields that comprise each item in the buffer. --- ----The GLSL version used for compute shaders is GLSL 430. +---Each field has a type, byte offset, and vertex attribute location. --- ----Currently, up to 32 shader flags are supported. ---- ----@param source string # The code or filename of the compute shader. ----@param options? {flags: table} # Optional settings for the Shader. ----@return lovr.Shader shader # The new compute Shader. -function lovr.graphics.newComputeShader(source, options) end +---@return table format # The format of the Buffer. +function Buffer:getFormat() end --- ----Creates a new Font. ---- ----It can be used to render text with `lovr.graphics.print`. +---Returns the length of the Buffer. --- ----Currently, the only supported font format is TTF. ---- ---- ----### NOTE: ----Larger font sizes will lead to more detailed curves at the cost of performance. ---- ----@overload fun(size?: number, padding?: number, spread?: number):lovr.Font ----@overload fun(rasterizer: lovr.Rasterizer, padding?: number, spread?: number):lovr.Font ----@param filename string # The filename of the font file. ----@param size? number # The size of the font, in pixels. ----@param padding? number # The number of pixels of padding around each glyph. ----@param spread? number # The range of the distance field, in pixels. ----@return lovr.Font font # The new Font. -function lovr.graphics.newFont(filename, size, padding, spread) end +---@return number length # The length of the Buffer. +function Buffer:getLength() end --- ----Creates a new Material. ---- ----Materials are sets of colors, textures, and other parameters that affect the appearance of objects. ---- ----They can be applied to `Model`s, `Mesh`es, and most graphics primitives accept a Material as an optional first argument. +---Returns a raw pointer to the Buffer's memory as a lightuserdata, intended for use with the LuaJIT ffi or for passing to C libraries. --- +---This is only available for temporary buffers, and as such the pointer is only valid until `lovr.graphics.submit` is called. --- ----### NOTE: ----- Scalar properties will default to `1.0`. ----- Color properties will default to `(1.0, 1.0, 1.0, 1.0)`, except for `emissive` which will ---- default to `(0.0, 0.0, 0.0, 0.0)`. ----- Textures will default to `nil` (a single 1x1 white pixel will be used for them). ---- ----@overload fun(texture: lovr.Texture, r?: number, g?: number, b?: number, a?: number):lovr.Material ----@overload fun(canvas: lovr.Canvas, r?: number, g?: number, b?: number, a?: number):lovr.Material ----@overload fun(r?: number, g?: number, b?: number, a?: number):lovr.Material ----@overload fun(hex?: number, a?: number):lovr.Material ----@return lovr.Material material # The new Material. -function lovr.graphics.newMaterial() end +---@return lightuserdata pointer # A pointer to the Buffer's memory. +function Buffer:getPointer() end --- ----Creates a new Mesh. ---- ----Meshes contain the data for an arbitrary set of vertices, and can be drawn. You must specify either the capacity for the Mesh or an initial set of vertex data. ---- ----Optionally, a custom format table can be used to specify the set of vertex attributes the mesh will provide to the active shader. +---Returns the size of the Buffer, in bytes. --- ----The draw mode and usage hint can also optionally be specified. ---- ----The default data type for an attribute is `float`, and the default component count is 1. ---- ---- ----### NOTE: ----Once created, the size and format of the Mesh cannot be changed.' +---This is the same as `length * stride`. --- ----The default mesh format is: ---- ---- { ---- { 'lovrPosition', 'float', 3 }, ---- { 'lovrNormal', 'float', 3 }, ---- { 'lovrTexCoord', 'float', 2 } ---- } ---- ----@overload fun(vertices: table, mode?: lovr.DrawMode, usage?: lovr.MeshUsage, readable?: boolean):lovr.Mesh ----@overload fun(blob: lovr.Blob, mode?: lovr.DrawMode, usage?: lovr.MeshUsage, readable?: boolean):lovr.Mesh ----@overload fun(format: table, size: number, mode?: lovr.DrawMode, usage?: lovr.MeshUsage, readable?: boolean):lovr.Mesh ----@overload fun(format: table, vertices: table, mode?: lovr.DrawMode, usage?: lovr.MeshUsage, readable?: boolean):lovr.Mesh ----@overload fun(format: table, blob: lovr.Blob, mode?: lovr.DrawMode, usage?: lovr.MeshUsage, readable?: boolean):lovr.Mesh ----@param size number # The maximum number of vertices the Mesh can store. ----@param mode? lovr.DrawMode # How the Mesh will connect its vertices into triangles. ----@param usage? lovr.MeshUsage # An optimization hint indicating how often the data in the Mesh will be updated. ----@param readable? boolean # Whether vertices from the Mesh can be read. ----@return lovr.Mesh mesh # The new Mesh. -function lovr.graphics.newMesh(size, mode, usage, readable) end +---@return number size # The size of the Buffer, in bytes. +function Buffer:getSize() end --- ----Creates a new Model from a file. ---- ----The supported 3D file formats are OBJ, glTF, and STL. +---Returns the distance between each item in the Buffer, in bytes. --- --- ---### NOTE: ----Diffuse and emissive textures will be loaded in the sRGB encoding, all other textures will be loaded as linear. +---When a Buffer is created, the stride can be set explicitly, otherwise it will be automatically computed based on the fields in the Buffer. --- ----Currently, the following features are not supported by the model importer: +---Strides can not be zero, and can not be smaller than the size of a single item. --- ----- OBJ: Quads are not supported (only triangles). ----- glTF: Sparse accessors are not supported. ----- glTF: Morph targets are not supported. ----- glTF: base64 images are not supported (base64 buffer data works though). ----- glTF: Only the default scene is loaded. ----- glTF: Currently, each skin in a Model can have up to 48 joints. ----- STL: ASCII STL files are not supported. +---To work around this, bind the Buffer as a storage buffer and fetch data from the buffer manually. --- ----@overload fun(modelData: lovr.ModelData):lovr.Model ----@param filename string # The filename of the model to load. ----@return lovr.Model model # The new Model. -function lovr.graphics.newModel(filename) end +---@return number stride # The stride of the Buffer, in bytes. +function Buffer:getStride() end --- ----Creates a new Shader. ---- +---Returns whether the Buffer is temporary. --- ----### NOTE: ----The `flags` table should contain string keys, with boolean or numeric values. ---- ----These flags can be used to customize the behavior of Shaders from Lua, by using the flags in the shader source code. ---- ----Numeric flags will be available as constants named `FLAG_<flagName>`. ---- ----Boolean flags can be used with `#ifdef` and will only be defined if the value in the Lua table was `true`. ---- ----The following flags are used by shaders provided by LÖVR: ---- ----- `animated` is a boolean flag that will cause the shader to position vertices based on the pose ---- of an animated skeleton. ---- ----This should usually only be used for animated `Model`s, since it ---- needs a skeleton to work properly and is slower than normal rendering. ----- `alphaCutoff` is a numeric flag that can be used to implement simple "cutout" style ---- transparency, where pixels with alpha below a certain threshold will be discarded. +---@return boolean temporary # Whether the Buffer is temporary. +function Buffer:isTemporary() end + --- ----The value ---- of the flag should be a number between 0.0 and 1.0, representing the alpha threshold. ----- `uniformScale` is a boolean flag used for optimization. +---Changes data in the Buffer using a table or a Blob. --- ----If the Shader is only going to be ---- used with objects that have a *uniform* scale (i.e. the x, y, and z components of the scale ---- are all the same number), then this flag can be set to use a faster method to compute the ---- `lovrNormalMatrix` uniform variable. ----- `multicanvas` is a boolean flag that should be set when rendering to multiple Textures ---- attached to a `Canvas`. +---This is supported for both temporary and permanent buffers. --- ----When set, the fragment shader should implement the `colors` function ---- instead of the `color` function, and can write color values to the `lovrCanvas` array instead ---- of returning a single color. +---All passes submitted to the GPU will use the new data. --- ----Each color in the array gets written to the corresponding ---- texture attached to the canvas. ----- `highp` is a boolean flag specific to mobile GPUs that changes the default precision for ---- fragment shaders to use high precision instead of the default medium precision. +---It is also possible to change the data in permanent buffers inside of a transfer pass using `Pass:copy`. --- ----This can fix ---- visual issues caused by a lack of precision, but isn't guaranteed to be supported on some ---- lower-end systems. ----- The following flags are used only by the `standard` PBR shader: ---- - `normalMap` should be set to `true` to render objects with a normal map, providing a more ---- detailed, bumpy appearance. +---Using a transfer pass allows the copy to happen after other passes in the frame. --- ----Currently, this requires the model to have vertex tangents. ---- - `emissive` should be set to `true` to apply emissive maps to rendered objects. --- ----This is ---- usually used to apply glowing lights or screens to objects, since the emissive texture is ---- not affected at all by lighting. ---- - `indirectLighting` is an *awesome* boolean flag that will apply realistic reflections and ---- lighting to the surface of an object, based on a specially-created skybox. +---### NOTE: +---When using a table, the table can contain a nested table for each value in the Buffer, or it can be a flat list of field component values. --- ----See the ---- `Standard Shader` guide for more information. ---- - `occlusion` is a boolean flag that uses the ambient occlusion texture in the model. +---It is not possible to mix both nested tables and flat values. --- ----It only ---- affects indirect lighting, so it will only have an effect if the `indirectLighting` flag is ---- also enabled. ---- - `skipTonemap` is a flag that will skip the tonemapping process. +---For each item updated, components of each field in the item (according to the Buffer's format) are read from either the nested subtable or the table itself. --- ----Tonemapping is an important ---- process that maps the high definition physical color values down to a 0 - 1 range for ---- display. +---A single number can be used to update a field with a scalar type. --- ----There are lots of different tonemapping algorithms that give different artistic ---- effects. +---Multiple numbers or a `lovr.math` vector can be used to update a field with a vector or mat4 type. --- ----The default tonemapping in the standard shader is the ACES algorithm, but you can ---- use this flag to turn off ACES and use your own tonemapping. +---Multiple numbers can be used to update mat2 and mat3 fields. --- ----Currently, up to 32 shader flags are supported. +---When updating normalized field types, components read from the table will be clamped to the normalized range ([0,1] or [-1,1]). --- ----The `stereo` option is only necessary for Android. +---In the Buffer, each field is written at its byte offset according to the Buffer's format, and subsequent items are separated by the byte stride of the Buffer. --- ----Currently on Android, only stereo shaders can be used with stereo Canvases, and mono Shaders can only be used with mono Canvases. +---Any missing components for an updated field will be set to zero. --- ----@overload fun(default: lovr.DefaultShader, options?: table):lovr.Shader ----@param vertex string # The code or filename of the vertex shader. If nil, the default vertex shader is used. ----@param fragment string # The code or filename of the fragment shader. If nil, the default fragment shader is used. ----@param options? {flags: table, stereo: boolean} # Optional settings for the Shader. ----@return lovr.Shader shader # The new Shader. -function lovr.graphics.newShader(vertex, fragment, options) end +---@overload fun(self: lovr.Buffer, blob: lovr.Blob, sourceOffset?: number, destinationOffset?: number, size?: number) +---@param data table # A flat or nested table of items to copy to the Buffer (see notes for format). +---@param sourceIndex? number # The index in the table to copy from. +---@param destinationIndex? number # The index of the first value in the Buffer to update. +---@param count? number # The number of values to update. `nil` will copy as many items as possible, based on the lengths of the source and destination. +function Buffer:setData(data, sourceIndex, destinationIndex, count) end --- ----Creates a new ShaderBlock from a table of variable definitions with their names and types. ---- ---- ----### NOTE: ----`compute` blocks can only be true if compute shaders are supported, see `lovr.graphics.getFeatures`. ---- ----Compute blocks may be slightly slower than uniform blocks, but they can also be much, much larger. ---- ----Uniform blocks are usually limited to around 16 kilobytes in size, depending on hardware. +---TODO --- ----@param type lovr.BlockType # Whether the block will be used for read-only uniform data or compute shaders. ----@param uniforms table # A table where the keys are uniform names and the values are uniform types. Uniform arrays can be specified by supplying a table as the uniform's value containing the type and the array size. ----@param flags? {usage: lovr.BufferUsage, readable: boolean} # Optional settings. ----@return lovr.ShaderBlock shaderBlock # The new ShaderBlock. -function lovr.graphics.newShaderBlock(type, uniforms, flags) end +---@class lovr.Font +local Font = {} --- ----Creates a new Texture from an image file. ---- ---- ----### NOTE: ----The "linear" flag should be set to true for textures that don't contain color information, such as normal maps. ---- ----Right now the supported image file formats are png, jpg, hdr, dds (DXT1, DXT3, DXT5), ktx, and astc. +---TODO --- ----@overload fun(images: table, flags?: table):lovr.Texture ----@overload fun(width: number, height: number, depth: number, flags?: table):lovr.Texture ----@overload fun(blob: lovr.Blob, flags?: table):lovr.Texture ----@overload fun(image: lovr.Image, flags?: table):lovr.Texture ----@param filename string # The filename of the image to load. ----@param flags? {linear: boolean, mipmaps: boolean, type: lovr.TextureType, format: lovr.TextureFormat, msaa: number} # Optional settings for the texture. ----@return lovr.Texture texture # The new Texture. -function lovr.graphics.newTexture(filename, flags) end +---@return number ascent # TODO +function Font:getAscent() end --- ----Resets the transformation to the origin. ---- +---TODO --- ----### NOTE: ----This is called at the beginning of every frame to reset the coordinate space. ---- -function lovr.graphics.origin() end +---@return number descent # TODO +function Font:getDescent() end --- ----Draws a plane with a given position, size, and orientation. ---- +---TODO --- ----### NOTE: ----The `u`, `v`, `w`, `h` arguments can be used to select a subregion of the diffuse texture to apply to the plane. +---@return number height # TODO +function Font:getHeight() end + --- ----One efficient technique for rendering many planes with different textures is to pack all of the textures into a single image, and then use the uv arguments to select a sub-rectangle to use for each plane. +---TODO --- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, width?: number, height?: number, angle?: number, ax?: number, ay?: number, az?: number, u?: number, v?: number, w?: number, h?: number) ----@param mode lovr.DrawStyle # How to draw the plane. ----@param x? number # The x coordinate of the center of the plane. ----@param y? number # The y coordinate of the center of the plane. ----@param z? number # The z coordinate of the center of the plane. ----@param width? number # The width of the plane, in meters. ----@param height? number # The height of the plane, in meters. ----@param angle? number # The number of radians to rotate around the rotation axis. ----@param ax? number # The x component of the rotation axis. ----@param ay? number # The y component of the rotation axis. ----@param az? number # The z component of the rotation axis. ----@param u? number # The u coordinate of the texture. ----@param v? number # The v coordinate of the texture. ----@param w? number # The width of the texture UVs to render. ----@param h? number # The height of the texture UVs to render. -function lovr.graphics.plane(mode, x, y, z, width, height, angle, ax, ay, az, u, v, w, h) end +---@param first lovr.Codepoint # TODO +---@param second lovr.Codepoint # TODO +---@return number kerning # TODO +function Font:getKerning(first, second) end --- ----Draws one or more points. +---TODO --- ----@overload fun(points: table) ----@param x number # The x coordinate of the point. ----@param y number # The y coordinate of the point. ----@param z number # The z coordinate of the point. ----@vararg number # More points. -function lovr.graphics.points(x, y, z, ...) end +---@return number spacing # TODO +function Font:getLineSpacing() end --- ----Pops the current transform from the stack, returning to the transformation that was applied before `lovr.graphics.push` was called. +---TODO --- +---@param text lovr.Text # TODO +---@param wrap number # TODO +---@return table lines # TODO +function Font:getLines(text, wrap) end + --- ----### NOTE: ----An error is thrown if there isn't a transform to pop. ---- ----This can happen if you forget to call push before calling pop, or if you have an unbalanced sequence of pushes and pops. +---TODO --- -function lovr.graphics.pop() end +---@return number density # TODO +function Font:getPixelDensity() end --- ----Presents the results of pending drawing operations to the window. +---TODO --- ----This is automatically called after `lovr.draw` by the default `lovr.run` function. ---- -function lovr.graphics.present() end +---@return lovr.Rasterizer rasterizer # The Rasterizer. +function Font:getRasterizer() end --- ----Draws text in 3D space using the active font. +---Returns a table of vertices for a piece of text, along with a Material to use when rendering it. The Material may change over time if the Font's texture atlas needs to be resized to make room for more glyphs. --- --- ---### NOTE: ----Unicode text is supported. ---- ----Use `\n` to add line breaks. +---Each vertex is a table of 4 floating point numbers with the following data: --- ----`\t` will be rendered as four spaces. +--- { x, y, u, v } --- ----LÖVR uses a fancy technique for font rendering called multichannel signed distance fields. +---These could be placed in a vertex buffer using the following buffer format: --- ----This leads to crisp text in VR, but requires a special shader to use. +--- { 'vec2:VertexPosition', 'vec2:VertexUV' } --- ----LÖVR internally switches to the appropriate shader, but only when the default shader is already set. ---- ----If you see strange font artifacts, make sure you switch back to the default shader by using `lovr.graphics.setShader()` before you draw text. ---- ----@param str string # The text to render. ----@param x? number # The x coordinate of the center of the text. ----@param y? number # The y coordinate of the center of the text. ----@param z? number # The z coordinate of the center of the text. ----@param scale? number # The scale of the text. ----@param angle? number # The number of radians to rotate the text around its rotation axis. ----@param ax? number # The x component of the axis of rotation. ----@param ay? number # The y component of the axis of rotation. ----@param az? number # The z component of the axis of rotation. ----@param wrap? number # The maximum width of each line, in meters (before scale is applied). Set to 0 or nil for no wrapping. ----@param halign? lovr.HorizontalAlign # The horizontal alignment. ----@param valign? lovr.VerticalAlign # The vertical alignment. -function lovr.graphics.print(str, x, y, z, scale, angle, ax, ay, az, wrap, halign, valign) end +---@param text lovr.Text # TODO +---@param wrap number # TODO +---@param halign lovr.HorizontalAlign # TODO +---@param valign lovr.VerticalAlign # TODO +---@return table vertices # The table of vertices. See below for the format of each vertex. +---@return lovr.Material material # A Material to use when rendering the vertices. +function Font:getVertices(text, wrap, halign, valign) end --- ----Pushes a copy of the current transform onto the transformation stack. +---TODO --- ----After changing the transform using `lovr.graphics.translate`, `lovr.graphics.rotate`, and `lovr.graphics.scale`, the original state can be restored using `lovr.graphics.pop`. ---- ---- ----### NOTE: ----An error is thrown if more than 64 matrices are pushed. ---- ----This can happen accidentally if a push isn't followed by a corresponding pop. ---- -function lovr.graphics.push() end +---@param text lovr.Text # TODO +---@return number width # TODO +function Font:getWidth(text) end --- ----Resets all graphics state to the initial values. +---TODO --- -function lovr.graphics.reset() end +---@param spacing number # TODO +function Font:setLineSpacing(spacing) end --- ----Rotates the coordinate system around an axis. ---- ----The rotation will last until `lovr.draw` returns or the transformation is popped off the transformation stack. +---TODO --- ---- ----### NOTE: ----Order matters when scaling, translating, and rotating the coordinate system. ---- ----@param angle? number # The amount to rotate the coordinate system by, in radians. ----@param ax? number # The x component of the axis of rotation. ----@param ay? number # The y component of the axis of rotation. ----@param az? number # The z component of the axis of rotation. -function lovr.graphics.rotate(angle, ax, ay, az) end +---@param density number # TODO +function Font:setPixelDensity(density) end --- ----Scales the coordinate system in 3 dimensions. ---- ----This will cause objects to appear bigger or smaller. ---- ----The scaling will last until `lovr.draw` returns or the transformation is popped off the transformation stack. +---TODO --- +---@class lovr.Material +local Material = {} + --- ----### NOTE: ----Order matters when scaling, translating, and rotating the coordinate system. +---Returns the properties of the Material in a table. --- ----@param x? number # The amount to scale on the x axis. ----@param y? number # The amount to scale on the y axis. ----@param z? number # The amount to scale on the z axis. -function lovr.graphics.scale(x, y, z) end +---@return table properties # The Material properties. +function Material:getProperties() end --- ----Enables or disables alpha sampling. +---Sets a texture for a Material. --- ----Alpha sampling is also known as alpha-to-coverage. +---Several predefined `MaterialTexture`s are supported. --- ----When it is enabled, the alpha channel of a pixel is factored into how antialiasing is computed, so the edges of a transparent texture will be correctly antialiased. +---Any texture that is `nil` will use a single white pixel as a fallback. --- --- ---### NOTE: ----- Alpha sampling is disabled by default. ----- This feature can be used for a simple transparency effect, pixels with an alpha of zero will ---- have their depth value discarded, allowing things behind them to show through (normally you ---- have to sort objects or write a shader for this). +---Textures must have a `TextureType` of `2d` to be used with Materials. --- ----@param enabled boolean # Whether or not alpha sampling is enabled. -function lovr.graphics.setAlphaSampling(enabled) end +---@overload fun(self: lovr.Material, texture: lovr.Texture) +---@param textureType? lovr.MaterialTexture # The type of texture to set. +---@param texture lovr.Texture # The texture to apply, or `nil` to use the default. +function Material:setTexture(textureType, texture) end --- ----Sets the background color used to clear the screen. ---- ----Color components are from 0.0 to 1.0. ---- +---TODO --- ----### NOTE: ----The default background color is `(0.0, 0.0, 0.0, 1.0)`. ---- ----@overload fun(hex: number, a?: number) ----@overload fun(color: table) ----@param r number # The red component of the background color. ----@param g number # The green component of the background color. ----@param b number # The blue component of the background color. ----@param a? number # The alpha component of the background color. -function lovr.graphics.setBackgroundColor(r, g, b, a) end +---@class lovr.Model +local Model = {} --- ----Sets the blend mode. ---- ----The blend mode controls how each pixel's color is blended with the previous pixel's color when drawn. +---TODO --- --- ---### NOTE: ----The default blend mode is `alpha` and `alphamultiply`. +---TODO What happens if the timestamp is before the first keyframe? TODO Does it loop? --- ----@overload fun() ----@param blend lovr.BlendMode # The blend mode. ----@param alphaBlend lovr.BlendAlphaMode # The alpha blend mode. -function lovr.graphics.setBlendMode(blend, alphaBlend) end +---@overload fun(self: lovr.Model, index: number, time: number, blend?: number) +---@param name string # The name of an animation in the model file. +---@param time number # The timestamp to evaluate the keyframes at, in seconds. +---@param blend? number # How much of the animation's pose to blend into the nodes, from 0 to 1. +function Model:animate(name, time, blend) end --- ----Sets or disables the active Canvas object. ---- ----If there is an active Canvas, things will be rendered to the Textures attached to that Canvas instead of to the headset. +---Returns the number of animations in the Model. --- ----@param canvas? lovr.Canvas # The new active Canvas object, or `nil` to just render to the headset. -function lovr.graphics.setCanvas(canvas) end +---@return number count # The number of animations in the Model. +function Model:getAnimationCount() end --- ----Sets the color used for drawing objects. ---- ----Color components are from 0.0 to 1.0. ---- ----Every pixel drawn will be multiplied (i.e. tinted) by this color. ---- ----This is a global setting, so it will affect all subsequent drawing operations. +---TODO --- --- ---### NOTE: ----The default color is `(1.0, 1.0, 1.0, 1.0)`. +---TODO how is duration calculated? --- ----@overload fun(hex: number, a?: number) ----@overload fun(color: table) ----@param r number # The red component of the color. ----@param g number # The green component of the color. ----@param b number # The blue component of the color. ----@param a? number # The alpha component of the color. -function lovr.graphics.setColor(r, g, b, a) end +---@overload fun(self: lovr.Model, name: string):number +---@param index number # The animation index. +---@return number duration # TODO +function Model:getAnimationDuration(index) end --- ----Enables and disables individual color channels. ---- ----When a color channel is enabled, it will be affected by drawing commands and clear commands. +---TODO --- ---- ----### NOTE: ----By default, all color channels are enabled. ---- ----Disabling all of the color channels can be useful if you only want to write to the depth buffer or the stencil buffer. ---- ----@param r boolean # Whether the red color channel should be enabled. ----@param g boolean # Whether the green color channel should be enabled. ----@param b boolean # Whether the blue color channel should be enabled. ----@param a boolean # Whether the alpha color channel should be enabled. -function lovr.graphics.setColorMask(r, g, b, a) end +---@param index number # TODO +---@return string name # The name of the animation. +function Model:getAnimationName(index) end --- ----Enables or disables culling. ---- ----Culling is an optimization that avoids rendering the back face of polygons. ---- ----This improves performance by reducing the number of polygons drawn, but requires that the vertices in triangles are specified in a consistent clockwise or counter clockwise order. ---- +---Returns the 6 values of the Model's axis-aligned bounding box. --- ----### NOTE: ----Culling is disabled by default. ---- ----@param isEnabled boolean # Whether or not culling should be enabled. -function lovr.graphics.setCullingEnabled(isEnabled) end +---@return number minx # The minimum x coordinate of the vertices in the Model. +---@return number maxx # The maximum x coordinate of the vertices in the Model. +---@return number miny # The minimum y coordinate of the vertices in the Model. +---@return number maxy # The maximum y coordinate of the vertices in the Model. +---@return number minz # The minimum z coordinate of the vertices in the Model. +---@return number maxz # The maximum z coordinate of the vertices in the Model. +function Model:getBoundingBox() end --- ----Sets the default filter mode for new Textures. ---- ----This controls how textures are sampled when they are minified, magnified, or stretched. ---- +---Returns a sphere approximately enclosing the vertices in the Model. --- ----### NOTE: ----The default filter is `trilinear`. ---- ----The maximum supported anisotropy level can be queried using `lovr.graphics.getLimits`. ---- ----@param mode lovr.FilterMode # The filter mode. ----@param anisotropy number # The level of anisotropy to use. -function lovr.graphics.setDefaultFilter(mode, anisotropy) end +---@return number x # The x coordinate of the position of the sphere. +---@return number y # The y coordinate of the position of the sphere. +---@return number z # The z coordinate of the position of the sphere. +---@return number radius # The radius of the bounding sphere. +function Model:getBoundingSphere() end --- ----Sets the current depth test. ---- ----The depth test controls how overlapping objects are rendered. ---- ---- ----### NOTE: ----The depth test is an advanced technique to control how 3D objects overlap each other when they are rendered. ---- ----It works as follows: ---- ----- Each pixel keeps track of its z value as well as its color. ----- If `write` is enabled when something is drawn, then any pixels that are drawn will have their ---- z values updated. ----- Additionally, anything drawn will first compare the existing z value of a pixel with the new z ---- value. ---- ----The `compareMode` setting determines how this comparison is performed. ---- ----If the ---- comparison succeeds, the new pixel will overwrite the previous one, otherwise that pixel won't ---- be rendered to. +---Returns the center of the Model's axis-aligned bounding box, relative to the Model's origin. --- ----Smaller z values are closer to the camera. +---@return number x # The x offset of the center of the bounding box. +---@return number y # The y offset of the center of the bounding box. +---@return number z # The z offset of the center of the bounding box. +function Model:getCenter() end + --- ----The default compare mode is `lequal`, which usually gives good results for normal 3D rendering. +---Returns the ModelData this Model was created from. --- ----@param compareMode? lovr.CompareMode # The new depth test. Use `nil` to disable the depth test. ----@param write? boolean # Whether pixels will have their z value updated when rendered to. -function lovr.graphics.setDepthTest(compareMode, write) end +---@return lovr.ModelData data # The ModelData. +function Model:getData() end --- ----Sets the active font used to render text with `lovr.graphics.print`. +---Returns the depth of the Model, computed from its axis-aligned bounding box. --- ----@param font? lovr.Font # The font to use. If `nil`, the default font is used (Varela Round). -function lovr.graphics.setFont(font) end +---@return number depth # The depth of the Model. +function Model:getDepth() end --- ----Sets the width of lines rendered using `lovr.graphics.line`. +---Returns the width, height, and depth of the Model, computed from its axis-aligned bounding box. --- +---@return number width # The width of the Model. +---@return number height # The height of the Model. +---@return number depth # The depth of the Model. +function Model:getDimensions() end + --- ----### NOTE: ----The default line width is `1`. +---Returns the height of the Model, computed from its axis-aligned bounding box. --- ----GPU driver support for line widths is poor. +---@return number height # The height of the Model. +function Model:getHeight() end + --- ----The actual width of lines may be different from what is set here. +---TODO --- ----In particular, some graphics drivers only support a line width of `1`. +---@return lovr.Buffer buffer # TODO +function Model:getIndexBuffer() end + --- ----Currently this function only supports integer values from 1 to 255. +---TODO --- ----@param width? number # The new line width, in pixels. -function lovr.graphics.setLineWidth(width) end +---@overload fun(self: lovr.Model, index: number):lovr.Material +---@param name string # The name of the Material to return. +---@return lovr.Material material # The material. +function Model:getMaterial(name) end --- ----Sets the width of drawn points, in pixels. +---Returns the number of materials in the Model. --- +---@return number count # The number of materials in the Model. +function Model:getMaterialCount() end + --- ----### NOTE: ----The default point size is `1.0`. +---TODO --- ----@param size? number # The new point size. -function lovr.graphics.setPointSize(size) end +---@param index number # TODO +---@return string name # The name of the material. +function Model:getMaterialName(index) end --- ----Sets the projection for a single view. +---Returns extra information stored in the model file. --- ----4 field of view angles can be used, similar to the field of view returned by `lovr.headset.getViewAngles`. +---Currently this is only implemented for glTF models and returns the JSON string from the glTF or glb file. --- ----Alternatively, a projection matrix can be used for other types of projections like orthographic, oblique, etc. +---The metadata can be used to get application-specific data or add support for glTF extensions not supported by LÖVR. --- ----Two views are supported, one for each eye. +---@return string metadata # The metadata from the model file. +function Model:getMetadata() end + --- ----When rendering to the headset, both projections are changed to match the ones used by the headset. +---Given a parent node, this function returns a table with the indices of its children. --- --- ---### NOTE: ----Non-stereo rendering will only use the first view. ---- ----The projection matrices are available as the `mat4 lovrProjections[2]` variable in shaders. ---- ----The current projection matrix is available as `lovrProjection`. +---If the node does not have any children, this function returns an empty table. --- ----@overload fun(view: number, matrix: lovr.Mat4) ----@param view number # The index of the view to update. ----@param left number # The left field of view angle, in radians. ----@param right number # The right field of view angle, in radians. ----@param up number # The top field of view angle, in radians. ----@param down number # The bottom field of view angle, in radians. -function lovr.graphics.setProjection(view, left, right, up, down) end +---@overload fun(self: lovr.Model, name: string):table +---@param index number # The index of the parent node. +---@return table children # A table containing a node index for each child of the node. +function Model:getNodeChildren(index) end --- ----Sets or disables the Shader used for drawing. +---Returns the number of nodes in the model. --- ----@overload fun() ----@param shader lovr.Shader # The shader to use. -function lovr.graphics.setShader(shader) end +---@return number count # The number of nodes in the model. +function Model:getNodeCount() end --- ----Sets the stencil test. ---- ----The stencil test lets you mask out pixels that meet certain criteria, based on the contents of the stencil buffer. +---TODO --- ----The stencil buffer can be modified using `lovr.graphics.stencil`. ---- ----After rendering to the stencil buffer, the stencil test can be set to control how subsequent drawing functions are masked by the stencil buffer. ---- ---- ----### NOTE: ----Stencil values are between 0 and 255. ---- ----By default, the stencil test is disabled. ---- ----@overload fun() ----@param compareMode lovr.CompareMode # The comparison method used to decide if a pixel should be visible, or nil if the stencil test is disabled. ----@param compareValue number # The value to compare stencil values to. -function lovr.graphics.setStencilTest(compareMode, compareValue) end +---@overload fun(self: lovr.Model, name: string, index: number):lovr.MeshMode, lovr.Material, number, number, number +---@param node number # The index of the node. +---@param index number # The index of the draw. +---@return lovr.MeshMode mode # Whether the vertices are points, lines, or triangles. +---@return lovr.Material material # The Material used by the draw. +---@return number start # The offset of the first vertex in the draw. +---@return number count # The number of vertices in the draw. +---@return number base # The base vertex of the draw (added to each instance value), or nil if the draw does not use an index buffer. +function Model:getNodeDraw(node, index) end --- ----Sets the pose for a single view. ---- ----Objects rendered in this view will appear as though the camera is positioned using the given pose. ---- ----Two views are supported, one for each eye. ---- ----When rendering to the headset, both views are changed to match the estimated eye positions. +---TODO --- ----These view poses are also available using `lovr.headset.getViewPose`. ---- ---- ----### NOTE: ----Non-stereo rendering will only use the first view. ---- ----The inverted view poses (view matrices) are available as the `mat4 lovrViews[2]` variable in shaders. ---- ----The current view matrix is available as `lovrView`. ---- ----@overload fun(view: number, matrix: lovr.Mat4, inverted: boolean) ----@param view number # The index of the view to update. ----@param x number # The x position of the viewer, in meters. ----@param y number # The y position of the viewer, in meters. ----@param z number # The z position of the viewer, in meters. ----@param angle number # The number of radians the viewer is rotated around its axis of rotation. ----@param ax number # The x component of the axis of rotation. ----@param ay number # The y component of the axis of rotation. ----@param az number # The z component of the axis of rotation. -function lovr.graphics.setViewPose(view, x, y, z, angle, ax, ay, az) end +---@overload fun(self: lovr.Model, name: string):number +---@param index number # The index of a node. +---@return number count # The number of draws in the node. +function Model:getNodeDrawCount(index) end --- ----Sets the polygon winding. +---TODO --- ----The winding direction determines which face of a triangle is the front face and which is the back face. ---- ----This lets the graphics engine cull the back faces of polygons, improving performance. ---- ----The default is counterclockwise. +---@param index number # TODO +---@return string name # TODO +function Model:getNodeName(index) end + --- +---TODO --- ----### NOTE: ----Culling is initially disabled and must be enabled using `lovr.graphics.setCullingEnabled`. +---@overload fun(self: lovr.Model, name: string, origin?: lovr.OriginType):number, number, number, number +---@param index number # The index of the node. +---@param origin? lovr.OriginType # Whether the orientation should be returned relative to the root node or the node's parent. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function Model:getNodeOrientation(index, origin) end + --- ----The default winding direction is counterclockwise. +---Given a child node, this function returns the index of its parent. --- ----@param winding lovr.Winding # The new winding direction. -function lovr.graphics.setWinding(winding) end +---@overload fun(self: lovr.Model, name: string):number +---@param index number # The index of the child node. +---@return number parent # The index of the parent. +function Model:getNodeParent(index) end --- ----Enables or disables wireframe rendering. +---TODO --- ----This is meant to be used as a debugging tool. +---@overload fun(self: lovr.Model, name: string, origin?: lovr.OriginType):number, number, number, number, number, number, number +---@param index number # The index of a node. +---@param origin? lovr.OriginType # Whether the pose should be returned relative to the root node or the node's parent. +---@return number x # The x position of the node. +---@return number y # The y position of the node. +---@return number z # The z position of the node. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function Model:getNodePose(index, origin) end + --- +---TODO --- ----### NOTE: ----Wireframe rendering is initially disabled. +---@overload fun(self: lovr.Model, name: string, space?: lovr.OriginType):number, number, number +---@param index number # The index of the node. +---@param space? lovr.OriginType # Whether the position should be returned relative to the root node or the node's parent. +---@return number x # The x coordinate. +---@return number y # The y coordinate. +---@return number z # The z coordinate. +function Model:getNodePosition(index, space) end + --- ----Wireframe rendering is only supported on desktop systems. +---TODO --- ----@param wireframe boolean # Whether or not wireframe rendering should be enabled. -function lovr.graphics.setWireframe(wireframe) end +---@overload fun(self: lovr.Model, name: string, origin?: lovr.OriginType):number, number, number +---@param index number # The index of the node. +---@param origin? lovr.OriginType # Whether the scale should be returned relative to the root node or the node's parent. +---@return number x # The x scale. +---@return number y # The y scale. +---@return number z # The z scale. +function Model:getNodeScale(index, origin) end --- ----Render a skybox from a texture. ---- ----Two common kinds of skybox textures are supported: A 2D equirectangular texture with a spherical coordinates can be used, or a "cubemap" texture created from 6 images. +---TODO --- ----@param texture lovr.Texture # The texture to use. -function lovr.graphics.skybox(texture) end +---@overload fun(self: lovr.Model, name: string, origin?: lovr.OriginType):number, number, number, number, number, number, number, number, number, number +---@param index number # The index of a node. +---@param origin? lovr.OriginType # Whether the transform should be returned relative to the root node or the node's parent. +---@return number x # The x position of the node. +---@return number y # The y position of the node. +---@return number z # The z position of the node. +---@return number sx # The x scale of the node. +---@return number sy # The y scale of the node. +---@return number sz # The z scale of the node. +---@return number angle # The number of radians the node is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function Model:getNodeTransform(index, origin) end --- ----Draws a sphere. +---Returns the index of the model's root node. --- ----@overload fun(material: lovr.Material, x?: number, y?: number, z?: number, radius?: number, angle?: number, ax?: number, ay?: number, az?: number) ----@param x? number # The x coordinate of the center of the sphere. ----@param y? number # The y coordinate of the center of the sphere. ----@param z? number # The z coordinate of the center of the sphere. ----@param radius? number # The radius of the sphere, in meters. ----@param angle? number # The rotation of the sphere around its rotation axis, in radians. ----@param ax? number # The x coordinate of the sphere's axis of rotation. ----@param ay? number # The y coordinate of the sphere's axis of rotation. ----@param az? number # The z coordinate of the sphere's axis of rotation. -function lovr.graphics.sphere(x, y, z, radius, angle, ax, ay, az) end +---@return number root # The index of the root node. +function Model:getRootNode() end --- ----Renders to the stencil buffer using a function. +---TODO --- +---@return lovr.Texture texture # TODO +function Model:getTexture() end + --- ----### NOTE: ----Stencil values are between 0 and 255. +---Returns the number of textures in the Model. --- ----@overload fun(callback: function, action?: lovr.StencilAction, value?: number, initial?: number) ----@param callback function # The function that will be called to render to the stencil buffer. ----@param action? lovr.StencilAction # How to modify the stencil value of pixels that are rendered to. ----@param value? number # If `action` is "replace", this is the value that pixels are replaced with. ----@param keep? boolean # If false, the stencil buffer will be cleared to zero before rendering. -function lovr.graphics.stencil(callback, action, value, keep) end +---@return number count # The number of textures in the Model. +function Model:getTextureCount() end --- ----Starts a named timer on the GPU, which can be stopped using `lovr.graphics.tock`. +---Returns the total number of triangles in the Model. --- --- ---### NOTE: ----The timer can be stopped by calling `lovr.graphics.tock` using the same name. ---- ----All drawing commands between the tick and the tock will be timed. ---- ----It is not possible to nest calls to tick and tock. ---- ----GPU timers are not supported on all systems. +---This isn't always related to the length of the vertex buffer, since a mesh in the Model could be drawn by multiple nodes. --- ----Check the `timers` feature using `lovr.graphics.getFeatures` to see if it is supported on the current system. ---- ----@param label string # The name of the timer. -function lovr.graphics.tick(label) end +---@return number count # The total number of triangles in the Model. +function Model:getTriangleCount() end --- ----Stops a named timer on the GPU, previously started with `lovr.graphics.tick`. ---- ---- ----### NOTE: ----All drawing commands between tick and tock will be timed. +---Returns 2 tables containing mesh data for the Model. --- ----It is not possible to nest calls to tick and tock. +---The first table is a list of vertex positions and contains 3 numbers for the x, y, and z coordinate of each vertex. --- ----The results are delayed, and might be `nil` for the first few frames. +---The second table is a list of triangles and contains 1-based indices into the first table representing the first, second, and third vertices that make up each triangle. --- ----This function returns the most recent available timer value. +---The vertex positions will be affected by node transforms. --- ----GPU timers are not supported on all systems. --- ----Check the `timers` feature using `lovr.graphics.getFeatures` to see if it is supported on the current system. +---### NOTE: +---After this function is called on a Model once, the result is cached (in its ModelData). --- ----@param label string # The name of the timer. ----@return number time # The number of seconds elapsed, or `nil` if the data isn't ready yet. -function lovr.graphics.tock(label) end +---@return table vertices # The triangle vertex positions, returned as a flat (non-nested) table of numbers. The position of each vertex is given as an x, y, and z coordinate. +---@return table indices # The vertex indices. Every 3 indices describes a triangle. +function Model:getTriangles() end --- ----Apply a transform to the coordinate system, changing its translation, rotation, and scale using a single function. ---- ----A `mat4` can also be used. ---- ----The transformation will last until `lovr.draw` returns or the transformation is popped off the transformation stack. +---TODO --- ----@overload fun(transform: lovr.mat4) ----@param x? number # The x component of the translation. ----@param y? number # The y component of the translation. ----@param z? number # The z component of the translation. ----@param sx? number # The x scale factor. ----@param sy? number # The y scale factor. ----@param sz? number # The z scale factor. ----@param angle? number # The number of radians to rotate around the rotation axis. ----@param ax? number # The x component of the axis of rotation. ----@param ay? number # The y component of the axis of rotation. ----@param az? number # The z component of the axis of rotation. -function lovr.graphics.transform(x, y, z, sx, sy, sz, angle, ax, ay, az) end +---@return lovr.Buffer buffer # TODO +function Model:getVertexBuffer() end --- ----Translates the coordinate system in three dimensions. ---- ----All graphics operations that use coordinates will behave as if they are offset by the translation value. ---- ----The translation will last until `lovr.draw` returns or the transformation is popped off the transformation stack. +---Returns the total vertex count of the Model. --- --- ---### NOTE: ----Order matters when scaling, translating, and rotating the coordinate system. +---This isn't always the same as the length of the vertex buffer, since a mesh in the Model could be drawn by multiple nodes. --- ----@param x? number # The amount to translate on the x axis. ----@param y? number # The amount to translate on the y axis. ----@param z? number # The amount to translate on the z axis. -function lovr.graphics.translate(x, y, z) end +---@return number count # The total number of vertices. +function Model:getVertexCount() end --- ----A Canvas is also known as a framebuffer or render-to-texture. +---Returns the width of the Model, computed from its axis-aligned bounding box. --- ----It allows you to render to a texture instead of directly to the screen. ---- ----This lets you postprocess or transform the results later before finally rendering them to the screen. +---@return number width # The width of the Model. +function Model:getWidth() end + --- ----After creating a Canvas, you can attach Textures to it using `Canvas:setTexture`. +---TODO --- --- ---### NOTE: ----Up to four textures can be attached to a Canvas and anything rendered to the Canvas will be broadcast to all attached Textures. ---- ----If you want to do render different things to different textures, use the `multicanvas` shader flag when creating your shader and implement the `void colors` function instead of the usual `vec4 color` function. +---TODO it's computed as skinCount TODO it's different from animationCount --- ----You can then assign different output colors to `lovrCanvas[0]`, `lovrCanvas[1]`, etc. instead of returning a single color. Each color written to the array will end up in the corresponding texture attached to the Canvas. ---- ----@class lovr.Canvas -local Canvas = {} +---@return boolean jointed # Whether the animation uses joints for skeletal animation. +function Model:hasJoints() end --- ----Returns the depth buffer used by the Canvas as a Texture. +---TODO --- ----If the Canvas was not created with a readable depth buffer (the `depth.readable` flag in `lovr.graphics.newCanvas`), then this function will return `nil`. ---- ----@return lovr.Texture texture # The depth Texture of the Canvas. -function Canvas:getDepthTexture() end +---@overload fun(self: lovr.Model, name: string, orientation: lovr.rotation, blend?: number) +---@param index number # The index of the node. +---@param orientation lovr.rotation # The target orientation. +---@param blend? number # A number from 0 to 1 indicating how much of the target orientation to blend in. A value of 0 will not change the node's orientation at all, whereas 1 will fully blend to the target orientation. +function Model:setNodeOrientation(index, orientation, blend) end --- ----Returns the dimensions of the Canvas, its Textures, and its depth buffer. +---TODO --- +---@overload fun(self: lovr.Model, name: string, position: lovr.vector3, orientation: lovr.rotation, blend?: number) +---@param index number # The index of the node. +---@param position lovr.vector3 # The target position. +---@param orientation lovr.rotation # The target orientation. +---@param blend? number # A number from 0 to 1 indicating how much of the target pose to blend in. A value of 0 will not change the node's pose at all, whereas 1 will fully blend to the target pose. +function Model:setNodePose(index, position, orientation, blend) end + --- ----### NOTE: ----The dimensions of a Canvas can not be changed after it is created. +---TODO --- ----@return number width # The width of the Canvas, in pixels. ----@return number height # The height of the Canvas, in pixels. -function Canvas:getDimensions() end +---@overload fun(self: lovr.Model, name: string, position: lovr.vector3, blend?: number) +---@param index number # The index of the node. +---@param position lovr.vector3 # The target position. +---@param blend? number # A number from 0 to 1 indicating how much of the target position to blend in. A value of 0 will not change the node's position at all, whereas 1 will fully blend to the target position. +function Model:setNodePosition(index, position, blend) end --- ----Returns the height of the Canvas, its Textures, and its depth buffer. +---TODO --- +---@overload fun(self: lovr.Model, name: string, scale: lovr.vector3, blend?: number) +---@param index number # The index of the node. +---@param scale lovr.vector3 # The target scale. +---@param blend? number # A number from 0 to 1 indicating how much of the target scale to blend in. A value of 0 will not change the node's scale at all, whereas 1 will fully blend to the target scale. +function Model:setNodeScale(index, scale, blend) end + --- ----### NOTE: ----The height of a Canvas can not be changed after it is created. +---TODO --- ----@return number height # The height of the Canvas, in pixels. -function Canvas:getHeight() end +---@overload fun(self: lovr.Model, name: string, transform: lovr.transform, blend?: number) +---@param index number # The index of the node. +---@param transform lovr.transform # The target transform. +---@param blend? number # A number from 0 to 1 indicating how much of the target transform to blend in. A value of 0 will not change the node's transform at all, whereas 1 will fully blend to the target transform. +function Model:setNodeTransform(index, transform, blend) end --- ----Returns the number of multisample antialiasing samples to use when rendering to the Canvas. Increasing this number will make the contents of the Canvas appear more smooth at the cost of performance. ---- ----It is common to use powers of 2 for this value. +---TODO --- +---@class lovr.Pass +local Pass = {} + --- ----### NOTE: ----All textures attached to the Canvas must be created with this MSAA value. +---TODO --- ----@return number samples # The number of MSAA samples. -function Canvas:getMSAA() end +---@param src lovr.Texture # TODO +---@param dst lovr.Texture # TODO +---@param srcx? number # TODO +---@param srcy? number # TODO +---@param srcz? number # TODO +---@param dstx? number # TODO +---@param dsty? number # TODO +---@param dstz? number # TODO +---@param srcw? number # TODO +---@param srch? number # TODO +---@param srcd? number # TODO +---@param dstw? number # TODO +---@param dsth? number # TODO +---@param dstd? number # TODO +---@param srclevel? number # TODO +---@param dstlevel? number # TODO +function Pass:blit(src, dst, srcx, srcy, srcz, dstx, dsty, dstz, srcw, srch, srcd, dstw, dsth, dstd, srclevel, dstlevel) end --- ----Returns the set of Textures currently attached to the Canvas. +---TODO --- --- ---### NOTE: ----Up to 4 Textures can be attached at once. +---TODO --- -function Canvas:getTexture() end +---@param transform lovr.Transform3 # The transform to apply to the box. +---@param style? lovr.DrawStyle # Whether the box should be drawn filled or outlined. +function Pass:box(transform, style) end --- ----Returns the width of the Canvas, its Textures, and its depth buffer. +---TODO --- --- ---### NOTE: ----The width of a Canvas can not be changed after it is created. +---TODO --- ----@return number width # The width of the Canvas, in pixels. -function Canvas:getWidth() end +---@overload fun(self: lovr.Pass, p1: lovr.Point3, p2: lovr.Point3, segments?: number) +---@param transform lovr.TransformXY2 # The transform to apply to the capsule. The x and y scale is the radius, the z scale is the length. +---@param segments? number # The number of circular segments to render. +function Pass:capsule(transform, segments) end --- ----Returns whether the Canvas was created with the `stereo` flag. ---- ----Drawing something to a stereo Canvas will draw it to two viewports in the left and right half of the Canvas, using transform information from two different eyes. ---- ----@return boolean stereo # Whether the Canvas is stereo. -function Canvas:isStereo() end - ---- ----Returns a new Image containing the contents of a Texture attached to the Canvas. +---TODO --- --- ---### NOTE: ----The Image will have the same pixel format as the Texture that is read from. +---TODO --- ----@param index? number # The index of the Texture to read from. ----@return lovr.Image image # The new Image. -function Canvas:newImage(index) end +---@param transform lovr.Transform # The transform to apply to the circle. +---@param style? lovr.DrawStyle # Whether the circle should be filled or outlined. +---@param angle1? number # The angle of the beginning of the arc. +---@param angle2? number # angle of the end of the arc. +---@param segments? number # The number of segments to render. +function Pass:circle(transform, style, angle1, angle2, segments) end --- ----Renders to the Canvas using a function. ---- ----All graphics functions inside the callback will affect the Canvas contents instead of directly rendering to the headset. ---- ----This can be used in `lovr.update`. +---TODO --- --- ---### NOTE: ----Make sure you clear the contents of the canvas before rendering by using `lovr.graphics.clear`. Otherwise there might be data in the canvas left over from a previous frame. ---- ----Also note that the transform stack is not modified by this function. +---TODO --- ----If you plan on modifying the transform stack inside your callback it may be a good idea to use `lovr.graphics.push` and `lovr.graphics.pop` so you can revert to the previous transform afterwards. ---- ----@param callback function # The function to use to render to the Canvas. ----@vararg any # Additional arguments to pass to the callback. -function Canvas:renderTo(callback, ...) end +---@overload fun(self: lovr.Pass, texture: lovr.Texture, color: lovr.Color, layer?: number, layers?: number, level?: number, levels?: number) +---@param buffer lovr.Buffer # The Buffer to clear. +---@param offset number # TODO +---@param extent number # TODO +function Pass:clear(buffer, offset, extent) end --- ----Attaches one or more Textures to the Canvas. ---- ----When rendering to the Canvas, everything will be drawn to all attached Textures. ---- ----You can attach different layers of an array, cubemap, or volume texture, and also attach different mipmap levels of Textures. +---TODO --- --- ---### NOTE: ----There are some restrictions on how textures can be attached: ---- ----- Up to 4 textures can be attached at once. ----- Textures must have the same dimensions and multisample settings as the Canvas. ---- ----To specify layers and mipmaps to attach, specify them after the Texture. ---- ----You can also optionally wrap them in a table. +---TODO --- ----@vararg any # One or more Textures to attach to the Canvas. -function Canvas:setTexture(...) end +---@overload fun(self: lovr.Pass, buffer: lovr.Buffer, offset?: number) +---@param x? number # How many workgroups to dispatch in the x dimension. +---@param y? number # How many workgroups to dispatch in the y dimension. +---@param z? number # How many workgroups to dispatch in the z dimension. +function Pass:compute(x, y, z) end --- ----A Font is an object created from a TTF file. +---TODO --- ----It can be used to render text with `lovr.graphics.print`. --- ----@class lovr.Font -local Font = {} - ---- ----Returns the maximum distance that any glyph will extend above the Font's baseline. ---- ----Units are generally in meters, see `Font:getPixelDensity`. +---### NOTE: +---TODO --- ----@return number ascent # The ascent of the Font. -function Font:getAscent() end +---@param transform lovr.TransformXY2 # The transform to apply to the cone. The x and y scale is the radius, the z scale is the length. +---@param segments? number # The number of circular segments to render. +function Pass:cone(transform, segments) end --- ----Returns the baseline of the Font. +---TODO --- ----This is where the characters "rest on", relative to the y coordinate of the drawn text. ---- ----Units are generally in meters, see `Font:setPixelDensity`. ---- ----@return number baseline # The baseline of the Font. -function Font:getBaseline() end +---@overload fun(self: lovr.Pass, blob: lovr.Blob, bufferdst: lovr.Buffer, srcoffset?: number, dstoffset?: number, size?: number) +---@overload fun(self: lovr.Pass, buffersrc: lovr.Buffer, bufferdst: lovr.Buffer, srcoffset?: number, dstoffset?: number, size?: number) +---@overload fun(self: lovr.Pass, image: lovr.Image, texturedst: lovr.Texture, srcx?: number, srcy?: number, dstx?: number, dsty?: number, width?: number, height?: number, srclayer?: number, dstlayer?: number, layers?: number, srclevel?: number, dstlevel?: number) +---@overload fun(self: lovr.Pass, texturesrc: lovr.Texture, texturedst: lovr.Texture, srcx?: number, srcy?: number, dstx?: number, dsty?: number, width?: number, height?: number, srclayer?: number, dstlayer?: number, layers?: number, srclevel?: number, dstlevel?: number) +---@overload fun(self: lovr.Pass, tally: lovr.Tally, srcindex?: number, dstoffset?: number, count?: number) +---@param table table # TODO +---@param bufferdst lovr.Buffer # TODO +---@param srcindex? number # TODO +---@param dstindex? number # TODO +---@param count? number # TODO +function Pass:copy(table, bufferdst, srcindex, dstindex, count) end --- ----Returns the maximum distance that any glyph will extend below the Font's baseline. +---TODO --- ----Units are generally in meters, see `Font:getPixelDensity` for more information. --- ----Note that due to the coordinate system for fonts, this is a negative value. +---### NOTE: +---TODO --- ----@return number descent # The descent of the Font. -function Font:getDescent() end +---@param transform lovr.Transform # The transform to apply to the cube. +---@param style? lovr.DrawStyle # Whether the cube should be drawn filled or outlined. +function Pass:cube(transform, style) end --- ----Returns the height of a line of text. ---- ----Units are in meters, see `Font:setPixelDensity`. ---- ----@return number height # The height of a rendered line of text. -function Font:getHeight() end - +---TODO --- ----Returns the current line height multiplier of the Font. --- ----The default is 1.0. +---### NOTE: +---TODO --- ----@return number lineHeight # The line height. -function Font:getLineHeight() end +---@overload fun(self: lovr.Pass, p1: lovr.Point3, p2: lovr.Point3, capped?: boolean, angle1?: number, angle2?: number, segments?: number) +---@param transform lovr.TransformXY2 # The transform to apply to the cylinder. The x and y scale is the radius, the z scale is the length. +---@param capped? boolean # Whether the tops and bottoms of the cylinder should be rendered. +---@param angle1? number # The angle of the beginning of the arc. +---@param angle2? number # angle of the end of the arc. +---@param segments? number # The number of circular segments to render. +function Pass:cylinder(transform, capped, angle1, angle2, segments) end --- ----Returns the current pixel density for the Font. ---- ----The default is 1.0. ---- ----Normally, this is in pixels per meter. ---- ----When rendering to a 2D texture, the units are pixels. +---TODO --- ----@return number pixelDensity # The current pixel density. -function Font:getPixelDensity() end +---@overload fun(self: lovr.Pass, model: lovr.Model, transform: lovr.Transform, nodename: string, children: boolean, instances: number) +---@param model lovr.Model # The model to draw. +---@param transform lovr.Transform # The transform of the object. +---@param nodeindex number # TODO +---@param children boolean # TODO +---@param instances number # TODO +function Pass:draw(model, transform, nodeindex, children, instances) end --- ----Returns the underlying `Rasterizer` object for a Font. +---TODO --- ----@return lovr.Rasterizer rasterizer # The rasterizer. -function Font:getRasterizer() end +---@overload fun(self: lovr.Pass) +---@param texture lovr.Texture # The texture to fill. +function Pass:fill(texture) end --- ----Returns the width and line count of a string when rendered using the font, taking into account an optional wrap limit. +---TODO --- --- ---### NOTE: ----To get the correct units returned, make sure the pixel density is set with ---- `Font:setPixelDensity`. +---TODO --- ----@param text string # The text to get the width of. ----@param wrap? number # The width at which to wrap lines, or 0 for no wrap. ----@return number width # The maximum width of any line in the text. ----@return number lines # The number of lines in the wrapped text. ----@return number lastwidth # The width of the last line of text (to assist in text layout). -function Font:getWidth(text, wrap) end +---@return table clears # TODO +function Pass:getClear() end --- ----Returns whether the Font has a set of glyphs. ---- ----Any combination of strings and numbers (corresponding to character codes) can be specified. +---TODO --- ----This function will return true if the Font is able to render *all* of the glyphs. ---- ---- ----### NOTE: ----It is a good idea to use this function when you're rendering an unknown or user-supplied string to avoid utterly embarrassing crashes. ---- ----@vararg any # Strings or numbers to test. ----@return boolean has # Whether the Font has the glyphs. -function Font:hasGlyphs(...) end +---@return number width # TODO +---@return number height # TODO +function Pass:getDimensions() end --- ----Sets the line height of the Font, which controls how far lines apart lines are vertically separated. +---TODO --- ----This value is a ratio and the default is 1.0. ---- ----@param lineHeight number # The new line height. -function Font:setLineHeight(lineHeight) end +---@return number height # TODO +function Pass:getHeight() end --- ----Sets the pixel density for the Font. ---- ----Normally, this is in pixels per meter. ---- ----When rendering to a 2D texture, the units are pixels. +---Returns the projection for a single view. --- ----@overload fun(self: lovr.Font) ----@param pixelDensity number # The new pixel density. -function Font:setPixelDensity(pixelDensity) end +---@overload fun(self: lovr.Pass, view: number, matrix: lovr.Mat4):lovr.Mat4 +---@param view number # The view index. +---@return number left # The left field of view angle, in radians. +---@return number right # The right field of view angle, in radians. +---@return number up # The top field of view angle, in radians. +---@return number down # The bottom field of view angle, in radians. +function Pass:getProjection(view) end --- ----A Material is an object used to control how objects appear, through coloring, texturing, and shading. ---- ----The Material itself holds sets of colors, textures, and other parameters that are made available to Shaders. +---TODO --- ----@class lovr.Material -local Material = {} +---@return number samples # TODO +function Pass:getSampleCount() end --- ----Returns a color property for a Material. +---TODO --- ----Different types of colors are supported for different lighting parameters. +---@return table target # TODO +function Pass:getTarget() end + --- ----Colors default to `(1.0, 1.0, 1.0, 1.0)` and are gamma corrected. +---TODO --- ----@param colorType? lovr.MaterialColor # The type of color to get. ----@return number r # The red component of the color. ----@return number g # The green component of the color. ----@return number b # The blue component of the color. ----@return number a # The alpha component of the color. -function Material:getColor(colorType) end +---@return lovr.PassType type # The type of the Pass. +function Pass:getType() end --- ----Returns a numeric property of a Material. +---TODO --- ----Scalar properties default to 1.0. ---- ----@param scalarType lovr.MaterialScalar # The type of property to get. ----@return number x # The value of the property. -function Material:getScalar(scalarType) end +---@return number views # TODO +function Pass:getViewCount() end --- ----Returns a texture for a Material. +---Get the pose of a single view. --- ----Several predefined `MaterialTexture`s are supported. +---@overload fun(self: lovr.Pass, view: number, matrix: lovr.Mat4, invert: boolean):lovr.Mat4 +---@param view number # The view index. +---@return number x # The x position of the viewer, in meters. +---@return number y # The y position of the viewer, in meters. +---@return number z # The z position of the viewer, in meters. +---@return number angle # The number of radians the viewer is rotated around its axis of rotation. +---@return number ax # The x component of the axis of rotation. +---@return number ay # The y component of the axis of rotation. +---@return number az # The z component of the axis of rotation. +function Pass:getViewPose(view) end + --- ----Any texture that is `nil` will use a single white pixel as a fallback. +---TODO --- ----@param textureType? lovr.MaterialTexture # The type of texture to get. ----@return lovr.Texture texture # The texture that is set, or `nil` if no texture is set. -function Material:getTexture(textureType) end +---@return number width # TODO +function Pass:getWidth() end --- ----Returns the transformation applied to texture coordinates of the Material. +---TODO --- --- ---### NOTE: ----Although texture coordinates will automatically be transformed by the Material's transform, the material transform is exposed as the `mat3 lovrMaterialTransform` uniform variable in shaders, allowing it to be used for other purposes. +---TODO --- ----@return number ox # The texture coordinate x offset. ----@return number oy # The texture coordinate y offset. ----@return number sx # The texture coordinate x scale. ----@return number sy # The texture coordinate y scale. ----@return number angle # The texture coordinate rotation, in radians. -function Material:getTransform() end +---@overload fun(self: lovr.Pass, t: table) +---@overload fun(self: lovr.Pass, v1: lovr.Vec3, v2: lovr.Vec3, ...) +---@param x1 number # The x coordinate of the first point. +---@param y1 number # The y coordinate of the first point. +---@param z1 number # The z coordinate of the first point. +---@param x2 number # The x coordinate of the next point. +---@param y2 number # The y coordinate of the next point. +---@param z2 number # The z coordinate of the next point. +---@vararg any # More points to add to the line. +function Pass:line(x1, y1, z1, x2, y2, z2, ...) end --- ----Sets a color property for a Material. +---TODO --- ----Different types of colors are supported for different lighting parameters. --- ----Colors default to `(1.0, 1.0, 1.0, 1.0)` and are gamma corrected. +---### NOTE: +---TODO --- ----@overload fun(self: lovr.Material, r: number, g: number, b: number, a?: number) ----@overload fun(self: lovr.Material, colorType?: lovr.MaterialColor, hex: number, a?: number) ----@overload fun(self: lovr.Material, hex: number, a?: number) ----@param colorType? lovr.MaterialColor # The type of color to set. ----@param r number # The red component of the color. ----@param g number # The green component of the color. ----@param b number # The blue component of the color. ----@param a? number # The alpha component of the color. -function Material:setColor(colorType, r, g, b, a) end +---@overload fun(self: lovr.Pass, vertices?: lovr.Buffer, indices: lovr.Buffer, transform: lovr.transform, start?: number, count?: number, instances?: number) +---@overload fun(self: lovr.Pass, vertices?: lovr.Buffer, indices: lovr.Buffer, draws: lovr.Buffer, drawcount: number, offset: number, stride: number) +---@param vertices? lovr.Buffer # TODO +---@param transform lovr.transform # The transform to apply to the mesh. +---@param start? number # The 1-based index of the first vertex to render from the vertex buffer (or the first index, when using an index buffer). +---@param count? number # The number of vertices to render (or the number of indices, when using an index buffer). When `nil`, as many vertices or indices as possible will be drawn (based on the length of the Buffers and `start`). +---@param instances? number # The number of copies of the mesh to render. +function Pass:mesh(vertices, transform, start, count, instances) end --- ----Sets a numeric property of a Material. +---TODO --- ----Scalar properties default to 1.0. ---- ----@param scalarType lovr.MaterialScalar # The type of property to set. ----@param x number # The value of the property. -function Material:setScalar(scalarType, x) end +---@param texture lovr.Texture # TODO +---@param base? number # TODO +---@param count? number # TODO +function Pass:mipmap(texture, base, count) end --- ----Sets a texture for a Material. +---TODO --- ----Several predefined `MaterialTexture`s are supported. +function Pass:origin() end + --- ----Any texture that is `nil` will use a single white pixel as a fallback. +---TODO --- --- ---### NOTE: ----Textures must have a `TextureType` of `2d` to be used with Materials. +---TODO --- ----@overload fun(self: lovr.Material, texture: lovr.Texture) ----@param textureType? lovr.MaterialTexture # The type of texture to set. ----@param texture lovr.Texture # The texture to apply, or `nil` to use the default. -function Material:setTexture(textureType, texture) end +---@param transform lovr.Transform2 # The transform to apply to the plane. +---@param style? lovr.DrawStyle # Whether the plane should be drawn filled or outlined. +---@param columns? number # The number of horizontal segments in the plane. +---@param rows? number # The number of vertical segments in the plane. +function Pass:plane(transform, style, columns, rows) end --- ----Sets the transformation applied to texture coordinates of the Material. ---- ----This lets you offset, scale, or rotate textures as they are applied to geometry. +---TODO --- --- ---### NOTE: ----Although texture coordinates will automatically be transformed by the Material's transform, the material transform is exposed as the `mat3 lovrMaterialTransform` uniform variable in shaders, allowing it to be used for other purposes. +---TODO --- ----@param ox number # The texture coordinate x offset. ----@param oy number # The texture coordinate y offset. ----@param sx number # The texture coordinate x scale. ----@param sy number # The texture coordinate y scale. ----@param angle number # The texture coordinate rotation, in radians. -function Material:setTransform(ox, oy, sx, sy, angle) end +---@overload fun(self: lovr.Pass, t: table) +---@overload fun(self: lovr.Pass, v: lovr.Vec3, ...) +---@param x number # The x coordinate of the first point. +---@param y number # The y coordinate of the first point. +---@param z number # The z coordinate of the first point. +---@vararg any # More points. +function Pass:points(x, y, z, ...) end --- ----A Mesh is a low-level graphics object that stores and renders a list of vertices. ---- ----Meshes are really flexible since you can pack pretty much whatever you want in them. ---- ----This makes them great for rendering arbitrary geometry, but it also makes them kinda difficult to use since you have to place each vertex yourself. ---- ----It's possible to batch geometry with Meshes too. ---- ----Instead of drawing a shape 100 times, it's much faster to pack 100 copies of the shape into a Mesh and draw the Mesh once. ---- ----Even storing just one copy in the Mesh and drawing that 100 times is usually faster. ---- ----Meshes are also a good choice if you have an object that changes its shape over time. +---TODO --- --- ---### NOTE: ----Each vertex in a Mesh can hold several pieces of data. ---- ----For example, you might want a vertex to keep track of its position, color, and a weight. ---- ----Each one of these pieces of information is called a vertex **attribute**. ---- ----A vertex attribute must have a name, a type, and a size. ---- ----Here's what the "position" attribute would look like as a Lua table: ---- ---- { 'vPosition', 'float', 3 } -- 3 floats, one for x, y, and z ---- ----Every vertex in a Mesh must have the same set of attributes. ---- ----We call this set of attributes the **format** of the Mesh, and it's specified as a simple table of attributes. ---- ----For example, we could represent the format described above as: ---- ---- { ---- { 'vPosition', 'float', 3 }, ---- { 'vColor', 'byte', 4 }, ---- { 'vWeight', 'int', 1 } ---- } +---TODO stack balancing/error --- ----When creating a Mesh, you can give it any format you want, or use the default. ---- ----The default Mesh format looks like this: ---- ---- { ---- { 'lovrPosition', 'float', 3 }, ---- { 'lovrNormal', 'float', 3 }, ---- { 'lovrTexCoord', 'float', 2 } ---- } ---- ----Great, so why do we go through the trouble of naming everything in our vertex and saying what type and size it is? The cool part is that we can access this data in a Shader. ---- ----We can write a vertex Shader that has `in` variables for every vertex attribute in our Mesh: ---- ---- in vec3 vPosition; ---- in vec4 vColor; ---- in int vWeight; ---- ---- vec4 position(mat4 projection, mat4 transform, vec4 vertex) { ---- // Here we can access the vPosition, vColor, and vWeight of each vertex in the Mesh! ---- } ---- ----Specifying custom vertex data is really powerful and is often used for lighting, animation, and more! ---- ----For more on the different data types available for the attributes, see `AttributeType`. ---- ----@class lovr.Mesh -local Mesh = {} +---@param stack? lovr.StackType # The type of stack to pop. +function Pass:pop(stack) end --- ----Attaches attributes from another Mesh onto this one. ---- ----This can be used to share vertex data across multiple meshes without duplicating the data, and can also be used for instanced rendering by using the `divisor` parameter. +---TODO --- --- ---### NOTE: ----The attribute divisor is a number used to control how the attribute data relates to instancing. If 0, then the attribute data is considered "per vertex", and each vertex will get the next element of the attribute's data. +---TODO stack balancing/error --- ----If the divisor 1 or more, then the attribute data is considered "per instance", and every N instances will get the next element of the attribute data. +---@param stack? lovr.StackType # The type of stack to push. +function Pass:push(stack) end + --- ----To prevent cycles, it is not possible to attach attributes onto a Mesh that already has attributes attached to a different Mesh. +---TODO --- ----@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, divisor?: number, ...) ----@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, divisor?: number, attributes: table) ----@param mesh lovr.Mesh # The Mesh to attach attributes from. ----@param divisor? number # The attribute divisor for all attached attributes. -function Mesh:attachAttributes(mesh, divisor) end +---@overload fun(self: lovr.Pass, texture: lovr.Texture, x?: number, y?: number, layer?: number, level?: number, width?: number, height?: number):lovr.Readback +---@overload fun(self: lovr.Pass, tally: lovr.Tally, index: number, count: number):lovr.Readback +---@param buffer lovr.Buffer # TODO +---@param index number # TODO +---@param count number # TODO +---@return lovr.Readback readback # TODO +function Pass:read(buffer, index, count) end --- ----Detaches attributes that were attached using `Mesh:attachAttributes`. +---TODO --- ----@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, ...) ----@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, attributes: table) ----@param mesh lovr.Mesh # A Mesh. The names of all of the attributes from this Mesh will be detached. -function Mesh:detachAttributes(mesh) end - --- ----Draws the contents of the Mesh. +---### NOTE: +---TODO axis does not need to be normalized TODO order matters --- ----@overload fun(self: lovr.Mesh, transform: lovr.mat4, instances?: number) ----@param x? number # The x coordinate to draw the Mesh at. ----@param y? number # The y coordinate to draw the Mesh at. ----@param z? number # The z coordinate to draw the Mesh at. ----@param scale? number # The scale to draw the Mesh at. ----@param angle? number # The angle to rotate the Mesh around the axis of rotation, in radians. +---@overload fun(self: lovr.Pass, q: lovr.Quat) +---@param angle? number # The number of radians to rotate around the axis of rotation. ---@param ax? number # The x component of the axis of rotation. ---@param ay? number # The y component of the axis of rotation. ---@param az? number # The z component of the axis of rotation. ----@param instances? number # The number of copies of the Mesh to draw. -function Mesh:draw(x, y, z, scale, angle, ax, ay, az, instances) end - ---- ----Get the draw mode of the Mesh, which controls how the vertices are connected together. ---- ----@return lovr.DrawMode mode # The draw mode of the Mesh. -function Mesh:getDrawMode() end - ---- ----Retrieve the current draw range for the Mesh. ---- ----The draw range is a subset of the vertices of the Mesh that will be drawn. ---- ----@return number start # The index of the first vertex that will be drawn, or nil if no draw range is set. ----@return number count # The number of vertices that will be drawn, or nil if no draw range is set. -function Mesh:getDrawRange() end +function Pass:rotate(angle, ax, ay, az) end --- ----Get the Material applied to the Mesh. +---TODO --- ----@return lovr.Material material # The current material applied to the Mesh. -function Mesh:getMaterial() end +---@overload fun(self: lovr.Pass, v: lovr.Vec3) +---@param x? number # The amount to scale the x axis. +---@param y? number # The amount to scale the y axis. +---@param z? number # The amount to scale the z axis. +function Pass:scale(x, y, z) end --- ----Gets the data for a single vertex in the Mesh. ---- ----The set of data returned depends on the Mesh's vertex format. ---- ----The default vertex format consists of 8 floating point numbers: the vertex position, the vertex normal, and the texture coordinates. ---- ----@param index number # The index of the vertex to retrieve. -function Mesh:getVertex(index) end - ---- ----Returns the components of a specific attribute of a single vertex in the Mesh. +---TODO --- --- ---### NOTE: ----Meshes without a custom format have the vertex position as their first attribute, the normal vector as the second attribute, and the texture coordinate as the third attribute. +---TODO --- ----@param index number # The index of the vertex to retrieve the attribute of. ----@param attribute number # The index of the attribute to retrieve the components of. -function Mesh:getVertexAttribute(index, attribute) end +---@overload fun(self: lovr.Pass, name: string, texture: lovr.Texture) +---@overload fun(self: lovr.Pass, name: string, sampler: lovr.Sampler) +---@overload fun(self: lovr.Pass, name: string, constant: any) +---@overload fun(self: lovr.Pass, binding: number, buffer: lovr.Buffer) +---@overload fun(self: lovr.Pass, binding: number, texture: lovr.Texture) +---@overload fun(self: lovr.Pass, binding: number, sampler: lovr.Sampler) +---@param name string # The name of the Shader variable. +---@param buffer lovr.Buffer # The Buffer to assign. +function Pass:send(name, buffer) end --- ----Returns the maximum number of vertices the Mesh can hold. +---TODO --- ---- ----### NOTE: ----The size can only be set when creating the Mesh, and cannot be changed afterwards. ---- ----A subset of the Mesh's vertices can be rendered, see `Mesh:setDrawRange`. ---- ----@return number size # The number of vertices the Mesh can hold. -function Mesh:getVertexCount() end +---@param enable boolean # Whether alpha to coverage should be enabled. +function Pass:setAlphaToCoverage(enable) end --- ----Get the format table of the Mesh's vertices. ---- ----The format table describes the set of data that each vertex contains. +---TODO --- ----@return table format # The table of vertex attributes. Each attribute is a table containing the name of the attribute, the `AttributeType`, and the number of components. -function Mesh:getVertexFormat() end - ---- ----Returns the current vertex map for the Mesh. --- ----The vertex map is a list of indices in the Mesh, allowing the reordering or reuse of vertices. +---### NOTE: +---TODO --- ----@overload fun(self: lovr.Mesh, t: table):table ----@overload fun(self: lovr.Mesh, blob: lovr.Blob) ----@return table map # The list of indices in the vertex map, or `nil` if no vertex map is set. -function Mesh:getVertexMap() end +---@param blend lovr.BlendMode # The blend mode. +---@param alphaBlend lovr.BlendAlphaMode # The alpha blend mode. +function Pass:setBlendMode(blend, alphaBlend) end --- ----Returns whether or not a vertex attribute is enabled. ---- ----Disabled attributes won't be sent to shaders. +---TODO --- ----@param attribute string # The name of the attribute. ----@return boolean enabled # Whether or not the attribute is enabled when drawing the Mesh. -function Mesh:isAttributeEnabled(attribute) end +---@param color lovr.Color # The new color. +function Pass:setColor(color) end --- ----Sets whether a vertex attribute is enabled. +---TODO --- ----Disabled attributes won't be sent to shaders. ---- ----@param attribute string # The name of the attribute. ----@param enabled boolean # Whether or not the attribute is enabled when drawing the Mesh. -function Mesh:setAttributeEnabled(attribute, enabled) end - --- ----Set a new draw mode for the Mesh. +---### NOTE: +---TODO --- ----@param mode lovr.DrawMode # The new draw mode for the Mesh. -function Mesh:setDrawMode(mode) end +---@param r boolean # Whether the red component should be affected by drawing. +---@param g boolean # Whether the green component should be affected by drawing. +---@param b boolean # Whether the blue component should be affected by drawing. +---@param a boolean # Whether the alpha component should be affected by drawing. +function Pass:setColorWrite(r, g, b, a) end --- ----Set the draw range for the Mesh. ---- ----The draw range is a subset of the vertices of the Mesh that will be drawn. ---- ----@overload fun(self: lovr.Mesh) ----@param start number # The first vertex that will be drawn. ----@param count number # The number of vertices that will be drawn. -function Mesh:setDrawRange(start, count) end - +---TODO --- ----Applies a Material to the Mesh. --- ----This will cause it to use the Material's properties whenever it is rendered. +---### NOTE: +---TODO --- ----@param material lovr.Material # The Material to apply. -function Mesh:setMaterial(material) end +---@param mode? lovr.CullMode # Whether `front` faces, `back` faces, or `none` of the faces should be culled. +function Pass:setCullMode(mode) end --- ----Update a single vertex in the Mesh. +---TODO --- --- ---### NOTE: ----Any unspecified components will be set to 0. +---TODO depthClamp feature! --- ----@param index number # The index of the vertex to set. ----@vararg number # The attributes of the vertex. -function Mesh:setVertex(index, ...) end +---@param enable boolean # Whether depth clamp should be enabled. +function Pass:setDepthClamp(enable) end --- ----Set the components of a specific attribute of a vertex in the Mesh. +---TODO --- --- ---### NOTE: ----Meshes without a custom format have the vertex position as their first attribute, the normal vector as the second attribute, and the texture coordinate as the third attribute. +---TODO --- ----@param index number # The index of the vertex to update. ----@param attribute number # The index of the attribute to update. ----@vararg number # The new components for the attribute. -function Mesh:setVertexAttribute(index, attribute, ...) end +---@param offset? number # The depth offset. +---@param sloped? number # The sloped depth offset. +function Pass:setDepthOffset(offset, sloped) end --- ----Sets the vertex map. +---TODO --- ----The vertex map is a list of indices in the Mesh, allowing the reordering or reuse of vertices. --- ----Often, a vertex map is used to improve performance, since it usually requires less data to specify the index of a vertex than it does to specify all of the data for a vertex. +---### NOTE: +---TODO --- ----@overload fun(self: lovr.Mesh, blob: lovr.Blob, size?: number) ----@param map table # The new vertex map. Each element of the table is an index of a vertex. -function Mesh:setVertexMap(map) end +---@overload fun(self: lovr.Pass) +---@param test lovr.CompareMode # The new depth test to use. +function Pass:setDepthTest(test) end --- ----Updates multiple vertices in the Mesh. +---TODO --- --- ---### NOTE: ----The start index plus the number of vertices in the table should not exceed the maximum size of the Mesh. +---TODO --- ----@overload fun(self: lovr.Mesh, blob: lovr.Blob, start?: number, count?: number) ----@param vertices table # The new set of vertices. ----@param start? number # The index of the vertex to start replacing at. ----@param count? number # The number of vertices to replace. If nil, all vertices will be used. -function Mesh:setVertices(vertices, start, count) end +---@param write boolean # The new depth write setting. +function Pass:setDepthWrite(write) end --- ----A Model is a drawable object loaded from a 3D file format. ---- ----The supported 3D file formats are OBJ, glTF, and STL. +---TODO --- ----@class lovr.Model -local Model = {} +---@param font lovr.Font # The Font to use when rendering text. +function Pass:setFont(font) end --- ----Applies an animation to the current pose of the Model. ---- ----The animation is evaluated at the specified timestamp, and mixed with the current pose of the Model using the alpha value. ---- ----An alpha value of 1.0 will completely override the pose of the Model with the animation's pose. ---- ---- ----### NOTE: ----For animations to properly show up, use a Shader created with the `animated` flag set to `true`. See `lovr.graphics.newShader` for more. ---- ----Animations are always mixed in with the current pose, and the pose only ever changes by calling `Model:animate` and `Model:pose`. +---TODO --- ----To clear the pose of a Model to the default, use `Model:pose(nil)`. ---- ----@overload fun(self: lovr.Model, index: number, time: number, alpha?: number) ----@param name string # The name of an animation. ----@param time number # The timestamp to evaluate the keyframes at, in seconds. ----@param alpha? number # How much of the animation to mix in, from 0 to 1. -function Model:animate(name, time, alpha) end +---@param material lovr.Material # TODO +function Pass:setMaterial(material) end --- ----Draw the Model. +---TODO --- ----@overload fun(self: lovr.Model, transform: lovr.mat4, instances?: number) ----@param x? number # The x coordinate to draw the Model at. ----@param y? number # The y coordinate to draw the Model at. ----@param z? number # The z coordinate to draw the Model at. ----@param scale? number # The scale to draw the Model at. ----@param angle? number # The angle to rotate the Model around the axis of rotation, in radians. ----@param ax? number # The x component of the axis of rotation. ----@param ay? number # The y component of the axis of rotation. ----@param az? number # The z component of the axis of rotation. ----@param instances? number # The number of copies of the Model to draw. -function Model:draw(x, y, z, scale, angle, ax, ay, az, instances) end +---@param mode lovr.MeshMode # TODO +function Pass:setMeshMode(mode) end --- ----Returns a bounding box that encloses the vertices of the Model. +---Sets the projection for a single view. --- ----@return number minx # The minimum x coordinate of the box. ----@return number maxx # The maximum x coordinate of the box. ----@return number miny # The minimum y coordinate of the box. ----@return number maxy # The maximum y coordinate of the box. ----@return number minz # The minimum z coordinate of the box. ----@return number maxz # The maximum z coordinate of the box. -function Model:getAABB() end - +---4 field of view angles can be used, similar to the field of view returned by `lovr.headset.getViewAngles`. --- ----Returns the number of animations in the Model. +---Alternatively, a projection matrix can be used for other types of projections like orthographic, oblique, etc. --- ----@return number count # The number of animations in the Model. -function Model:getAnimationCount() end - +---There is also a shorthand string "orthographic" that can be used to configure an orthographic projection. --- ----Returns the duration of an animation in the Model, in seconds. +---Up to 6 views are supported. --- ----@overload fun(self: lovr.Model, index: number):number ----@param name string # The name of the animation. ----@return number duration # The duration of the animation, in seconds. -function Model:getAnimationDuration(name) end - +---When rendering to the headset, both projections are changed to match the ones used by the headset. --- ----Returns the name of one of the animations in the Model. +---This is also available by calling `lovr.headset.getViewAngles`. --- ----@param index number # The index of the animation to get the name of. ----@return string name # The name of the animation. -function Model:getAnimationName(index) end - --- ----Returns a Material loaded from the Model, by name or index. +---### NOTE: +---A far clipping plane of 0.0 can be used for an infinite far plane with reversed Z range. --- ----This includes `Texture` objects and other properties like colors, metalness/roughness, and more. +---This is the default. --- ----@overload fun(self: lovr.Model, index: number):lovr.Material ----@param name string # The name of the Material to return. ----@return lovr.Material material # The material. -function Model:getMaterial(name) end +---@overload fun(self: lovr.Pass, view: number, matrix: lovr.Mat4) +---@param view number # The index of the view to update. +---@param left number # The left field of view angle, in radians. +---@param right number # The right field of view angle, in radians. +---@param up number # The top field of view angle, in radians. +---@param down number # The bottom field of view angle, in radians. +---@param near? number # The near clipping plane distance, in meters. +---@param far? number # The far clipping plane distance, in meters. +function Pass:setProjection(view, left, right, up, down, near, far) end --- ----Returns the number of materials in the Model. +---TODO --- ----@return number count # The number of materials in the Model. -function Model:getMaterialCount() end +---@param sampler lovr.Sampler # TODO +function Pass:setSampler(sampler) end --- ----Returns the name of one of the materials in the Model. +---TODO --- ----@param index number # The index of the material to get the name of. ----@return string name # The name of the material. -function Model:getMaterialName(index) end - --- ----Returns the number of nodes (bones) in the Model. +---### NOTE: +---TODO not floating point, negative, limits, not pipeline, initial pass state --- ----@return number count # The number of nodes in the Model. -function Model:getNodeCount() end +---@param x number # The x coordinate of the upper-left corner of the scissor rectangle. +---@param y number # The y coordinate of the upper-left corner of the scissor rectangle. +---@param w number # The width of the scissor rectangle. +---@param h number # The height of the scissor rectangle. +function Pass:setScissor(x, y, w, h) end --- ----Returns the name of one of the nodes (bones) in the Model. +---TODO --- ----@param index number # The index of the node to get the name of. ----@return string name # The name of the node. -function Model:getNodeName(index) end +---@overload fun(self: lovr.Pass, default: lovr.DefaultShader) +---@overload fun(self: lovr.Pass) +---@param shader lovr.Shader # A custom Shader object to use for rendering. +function Pass:setShader(shader) end --- ----Returns the pose of a single node in the Model in a given `CoordinateSpace`. +---TODO --- --- ---### NOTE: ----For skinned nodes to render correctly, use a Shader created with the `animated` flag set to `true`. +---TODO --- ----See `lovr.graphics.newShader` for more. ---- ----@overload fun(self: lovr.Model, index: number, space?: lovr.CoordinateSpace):number, number, number, number, number, number, number ----@param name string # The name of the node. ----@param space? lovr.CoordinateSpace # Whether the pose should be returned relative to the node's parent or relative to the root node of the Model. ----@return number x # The x position of the node. ----@return number y # The y position of the node. ----@return number z # The z position of the node. ----@return number angle # The number of radians the node is rotated around its rotational axis. ----@return number ax # The x component of the axis of rotation. ----@return number ay # The y component of the axis of rotation. ----@return number az # The z component of the axis of rotation. -function Model:getNodePose(name, space) end +---@overload fun(self: lovr.Pass) +---@param test lovr.CompareMode # The new stencil test to use. +---@param value number # The stencil value to compare against. +---@param mask? number # An optional mask to apply to stencil values before the comparison. +function Pass:setStencilTest(test, value, mask) end --- ----Returns 2 tables containing mesh data for the Model. +---TODO --- ----The first table is a list of vertex positions and contains 3 numbers for the x, y, and z coordinate of each vertex. ---- ----The second table is a list of triangles and contains 1-based indices into the first table representing the first, second, and third vertices that make up each triangle. --- ----The vertex positions will be affected by node transforms. +---### NOTE: +---TODO --- ----@return table vertices # A flat table of numbers containing vertex positions. ----@return table indices # A flat table of numbers containing triangle vertex indices. -function Model:getTriangles() end +---@overload fun(self: lovr.Pass, actions: table, value?: number, mask?: number) +---@overload fun(self: lovr.Pass) +---@param action lovr.StencilAction # How pixels drawn will update the stencil buffer. +---@param value? number # When using the 'replace' action, this is the value to replace with. +---@param mask? number # An optional mask to apply to stencil values before writing. +function Pass:setStencilWrite(action, value, mask) end --- ----Returns whether the Model has any nodes associated with animated joints. +---Sets the pose for a single view. --- ----This can be used to approximately determine whether an animated shader needs to be used with an arbitrary Model. +---Objects rendered in this view will appear as though the camera is positioned using the given pose. --- +---Up to 6 views are supported. --- ----### NOTE: ----A model can still be animated even if this function returns false, since node transforms can still be animated with keyframes without skinning. +---When rendering to the headset, views are changed to match the eye positions. --- ----These types of animations don't need to use a Shader with the `animated = true` flag, though. +---These view poses are also available using `lovr.headset.getViewPose`. --- ----@return boolean skeletal # Whether the Model has any nodes that use skeletal animation. -function Model:hasJoints() end +---@overload fun(self: lovr.Pass, view: number, matrix: lovr.Mat4, inverted: boolean) +---@param view number # The index of the view to update. +---@param x number # The x position of the viewer, in meters. +---@param y number # The y position of the viewer, in meters. +---@param z number # The z position of the viewer, in meters. +---@param angle number # The number of radians the viewer is rotated around its axis of rotation. +---@param ax number # The x component of the axis of rotation. +---@param ay number # The y component of the axis of rotation. +---@param az number # The z component of the axis of rotation. +function Pass:setViewPose(view, x, y, z, angle, ax, ay, az) end --- ----Applies a pose to a single node of the Model. ---- ----The input pose is assumed to be relative to the pose of the node's parent. ---- ----This is useful for applying inverse kinematics (IK) to a chain of bones in a skeleton. ---- ----The alpha parameter can be used to mix between the node's current pose and the input pose. +---TODO --- --- ---### NOTE: ----For skinned nodes to render correctly, use a Shader created with the `animated` flag set to `true`. +---TODO floating point, negative, flipped depth range, limits, not pipeline, initial pass state, what the hell is depth range --- ----See `lovr.graphics.newShader` for more. ---- ----@overload fun(self: lovr.Model, index: number, x: number, y: number, z: number, angle: number, ax: number, ay: number, az: number, alpha?: number) ----@overload fun(self: lovr.Model) ----@param name string # The name of the node. ----@param x number # The x position. ----@param y number # The y position. ----@param z number # The z position. ----@param angle number # The angle of rotation around the axis, in radians. ----@param ax number # The x component of the rotation axis. ----@param ay number # The y component of the rotation axis. ----@param az number # The z component of the rotation axis. ----@param alpha? number # How much of the pose to mix in, from 0 to 1. -function Model:pose(name, x, y, z, angle, ax, ay, az, alpha) end +---@param x number # The x coordinate of the upper-left corner of the viewport. +---@param y number # The y coordinate of the upper-left corner of the viewport. +---@param w number # The width of the viewport. +---@param h number # The height of the viewport. +---@param minDepth? number # The min component of the depth range. +---@param maxDepth? number # The max component of the depth range. +function Pass:setViewport(x, y, w, h, minDepth, maxDepth) end --- ----Shaders are GLSL programs that transform the way vertices and pixels show up on the screen. They can be used for lighting, postprocessing, particles, animation, and much more. ---- ----You can use `lovr.graphics.setShader` to change the active Shader. +---TODO --- --- ---### NOTE: ----GLSL version `330` is used on desktop systems, and `300 es` on WebGL/Android. ---- ----The default vertex shader: ---- ---- vec4 position(mat4 projection, mat4 transform, vec4 vertex) { ---- return projection * transform * vertex; ---- } ---- ----The default fragment shader: ---- ---- vec4 color(vec4 graphicsColor, sampler2D image, vec2 uv) { ---- return graphicsColor * lovrDiffuseColor * lovrVertexColor * texture(image, uv); ---- } ---- ----Additionally, the following headers are prepended to the shader source, giving you convenient access to a default set of uniform variables and vertex attributes. ---- ----Vertex shader header: ---- ---- in vec3 lovrPosition; // The vertex position ---- in vec3 lovrNormal; // The vertex normal vector ---- in vec2 lovrTexCoord; ---- in vec4 lovrVertexColor; ---- in vec3 lovrTangent; ---- in uvec4 lovrBones; ---- in vec4 lovrBoneWeights; ---- in uint lovrDrawID; ---- out vec4 lovrGraphicsColor; ---- uniform mat4 lovrModel; ---- uniform mat4 lovrView; ---- uniform mat4 lovrProjection; ---- uniform mat4 lovrTransform; // Model-View matrix ---- uniform mat3 lovrNormalMatrix; // Inverse-transpose of lovrModel ---- uniform mat3 lovrMaterialTransform; ---- uniform float lovrPointSize; ---- uniform mat4 lovrPose[48]; ---- uniform int lovrViewportCount; ---- uniform int lovrViewID; ---- const mat4 lovrPoseMatrix; // Bone-weighted pose ---- const int lovrInstanceID; // Current instance ID ---- ----Fragment shader header: ---- ---- in vec2 lovrTexCoord; ---- in vec4 lovrVertexColor; ---- in vec4 lovrGraphicsColor; ---- out vec4 lovrCanvas[gl_MaxDrawBuffers]; ---- uniform float lovrMetalness; ---- uniform float lovrRoughness; ---- uniform vec4 lovrDiffuseColor; ---- uniform vec4 lovrEmissiveColor; ---- uniform sampler2D lovrDiffuseTexture; ---- uniform sampler2D lovrEmissiveTexture; ---- uniform sampler2D lovrMetalnessTexture; ---- uniform sampler2D lovrRoughnessTexture; ---- uniform sampler2D lovrOcclusionTexture; ---- uniform sampler2D lovrNormalTexture; ---- uniform samplerCube lovrEnvironmentTexture; ---- uniform int lovrViewportCount; ---- uniform int lovrViewID; ---- ----### Compute Shaders ---- ----Compute shaders can be created with `lovr.graphics.newComputeShader` and run with `lovr.graphics.compute`. ---- ----Currently, compute shaders are written with raw GLSL. ---- ----There is no default compute shader, instead the `void compute();` function must be implemented. +---TODO --- ----You can use the `layout` qualifier to specify a local work group size: ---- ---- layout(local_size_x = X, local_size_y = Y, local_size_z = Z) in; ---- ----And the following built in variables can be used: ---- ---- in uvec3 gl_NumWorkGroups; // The size passed to lovr.graphics.compute ---- in uvec3 gl_WorkGroupSize; // The local work group size ---- in uvec3 gl_WorkGroupID; // The current global work group ---- in uvec3 gl_LocalInvocationID; // The current local work group ---- in uvec3 gl_GlobalInvocationID; // A unique ID combining the global and local IDs ---- in uint gl_LocalInvocationIndex; // A 1D index of the LocalInvocationID ---- ----Compute shaders don't return anything but they can write data to `Texture`s or `ShaderBlock`s. To bind a texture in a way that can be written to a compute shader, declare the uniforms with a type of `image2D`, `imageCube`, etc. instead of the usual `sampler2D` or `samplerCube`. ---- ----Once a texture is bound to an image uniform, you can use the `imageLoad` and `imageStore` GLSL functions to read and write pixels in the image. ---- ----Variables in `ShaderBlock`s can be written to using assignment syntax. ---- ----LÖVR handles synchronization of textures and shader blocks so there is no need to use manual memory barriers to synchronize writes to resources from compute shaders. ---- ----@class lovr.Shader -local Shader = {} +---@param winding lovr.Winding # Whether triangle vertices are ordered `clockwise` or `counterclockwise`. +function Pass:setWinding(winding) end --- ----Returns the type of the Shader, which will be "graphics" or "compute". +---TODO --- ----Graphics shaders are created with `lovr.graphics.newShader` and can be used for rendering with `lovr.graphics.setShader`. --- ----Compute shaders are created with `lovr.graphics.newComputeShader` and can be run using `lovr.graphics.compute`. +---### NOTE: +---TODO --- ----@return lovr.ShaderType type # The type of the Shader. -function Shader:getType() end +---@param enable boolean # Whether wireframe rendering should be enabled. +function Pass:setWireframe(enable) end --- ----Returns whether a Shader has a block. ---- ----A block is added to the Shader code at creation time using `ShaderBlock:getShaderCode`. +---TODO --- ----The block name (not the namespace) is used to link up the ShaderBlock object to the Shader. --- ----This function can be used to check if a Shader was created with a block using the given name. +---### NOTE: +---TODO --- ----@param block string # The name of the block. ----@return boolean present # Whether the shader has the specified block. -function Shader:hasBlock(block) end +---@overload fun(self: lovr.Pass) +---@param skybox lovr.Texture # The skybox to render. Its `TextureType` can be `cube` to render as a cubemap, or `2d` to render as an equirectangular (spherical) 2D image. +function Pass:skybox(skybox) end --- ----Returns whether a Shader has a particular uniform variable. +---TODO --- --- ---### NOTE: ----If a uniform variable is defined but unused in the shader, the shader compiler will optimize it out and the uniform will not report itself as present. +---TODO --- ----@param uniform string # The name of the uniform variable. ----@return boolean present # Whether the shader has the specified uniform. -function Shader:hasUniform(uniform) end +---@param transform lovr.transform # The transform to apply to the sphere. +---@param longitudes? number # The number of "horizontal" segments. +---@param latitudes? number # The number of "vertical" segments. +function Pass:sphere(transform, longitudes, latitudes) end --- ----Updates a uniform variable in the Shader. +---TODO --- --- ---### NOTE: ----The shader does not need to be active to update its uniforms. ---- ----The following type combinations are supported: ---- ----<table> ---- <thead> ---- <tr> ---- <td>Uniform type</td> ---- <td>LÖVR type</td> ---- </tr> ---- </thead> ---- <tbody> ---- <tr> ---- <td>float</td> ---- <td>number</td> ---- </tr> ---- <tr> ---- <td>int</td> ---- <td>number</td> ---- </tr> ---- <tr> ---- <td>vec2</td> ---- <td>{ x, y }</td> ---- </tr> ---- <tr> ---- <td>vec3</td> ---- <td>{ x, y, z } or vec3</td> ---- </tr> ---- <tr> ---- <td>vec4</td> ---- <td>{ x, y, z, w }</td> ---- </tr> ---- <tr> ---- <td>ivec2</td> ---- <td>{ x, y }</td> ---- </tr> ---- <tr> ---- <td>ivec3</td> ---- <td>{ x, y, z }</td> ---- </tr> ---- <tr> ---- <td>ivec4</td> ---- <td>{ x, y, z, w }</td> ---- </tr> ---- <tr> ---- <td>mat2</td> ---- <td>{ x, ... }</td> ---- </tr> ---- <tr> ---- <td>mat3</td> ---- <td>{ x, ... }</td> ---- </tr> ---- <tr> ---- <td>mat4</td> ---- <td>{ x, ... } or mat4</td> ---- </tr> ---- <tr> ---- <td>sampler</td> ---- <td>Texture</td> ---- </tr> ---- <tr> ---- <td>image</td> ---- <td>Texture</td> ---- </tr> ---- </tbody> </table> ---- ----Uniform arrays can be wrapped in tables or passed as multiple arguments. ---- ----Textures must match the type of sampler or image they are being sent to. ---- ----The following sampler (and image) types are currently supported: +---TODO --- ----- `sampler2D` ----- `sampler3D` ----- `samplerCube` ----- `sampler2DArray` +---@overload fun(self: lovr.Pass, colortext: table, transform: lovr.transform, wrap?: number, halign?: lovr.HorizontalAlign, valign?: lovr.VerticalAlign) +---@param text string # The text to render. +---@param transform lovr.transform # The transform of the text. +---@param wrap? number # The maximum width of each line in meters (before scale is applied). When zero, the text will not wrap. +---@param halign? lovr.HorizontalAlign # The horizontal alignment. +---@param valign? lovr.VerticalAlign # The vertical alignment. +function Pass:text(text, transform, wrap, halign, valign) end + --- ----`Blob`s can be used to pass arbitrary binary data to Shader variables. +---TODO --- ----@param uniform string # The name of the uniform to update. ----@param value any # The new value of the uniform. ----@return boolean success # Whether the uniform exists and was updated. -function Shader:send(uniform, value) end +---@param tally lovr.Tally # TODO +---@param index number # TODO +function Pass:tick(tally, index) end --- ----Sends a ShaderBlock to a Shader. +---TODO --- ----After the block is sent, you can update the data in the block without needing to resend the block. +---@param tally lovr.Tally # TODO +---@param index number # TODO +function Pass:tock(tally, index) end + --- ----The block can be sent to multiple shaders and they will all see the same data from the block. +---TODO --- --- ---### NOTE: ----The Shader does not need to be active to send it a block. +---TODO --- ----Make sure the ShaderBlock's variables line up with the block variables declared in the shader code, otherwise you'll get garbage data in the block. ---- ----An easy way to do this is to use `ShaderBlock:getShaderCode` to get a GLSL snippet that is compatible with the block. ---- ----@param name string # The name of the block to send to. ----@param block lovr.ShaderBlock # The ShaderBlock to associate with the specified block. ----@param access? lovr.UniformAccess # How the Shader will use this block (used as an optimization hint). -function Shader:sendBlock(name, block, access) end +---@param transform lovr.TransformXY2 # The transform to apply to the torus. The x scale is the radius, the z scale is the thickness. +---@param tsegments? number # The number of toroidal (circular) segments to render. +---@param psegments? number # The number of poloidal (tubular) segments to render. +function Pass:torus(transform, tsegments, psegments) end --- ----Sends a Texture to a Shader for writing. +---TODO --- ----This is meant to be used with compute shaders and only works with uniforms declared as `image2D`, `imageCube`, `image2DArray`, and `image3D`. --- ----The normal `Shader:send` function accepts Textures and should be used most of the time. +---### NOTE: +---TODO you can use combos of numbers/vectors/quats too (or use meta Transform type to explain) --- ----@overload fun(self: lovr.Shader, name: string, index: number, texture: lovr.Texture, slice?: number, mipmap?: number, access?: lovr.UniformAccess) ----@param name string # The name of the image uniform. ----@param texture lovr.Texture # The Texture to assign. ----@param slice? number # The slice of a cube, array, or volume texture to use, or `nil` for all slices. ----@param mipmap? number # The mipmap of the texture to use. ----@param access? lovr.UniformAccess # Whether the image will be read from, written to, or both. -function Shader:sendImage(name, texture, slice, mipmap, access) end +---@overload fun(self: lovr.Pass, transform: lovr.Mat4) +---@param x? number # The x component of the translation. +---@param y? number # The y component of the translation. +---@param z? number # The z component of the translation. +---@param sx? number # The x scale factor. +---@param sy? number # The y scale factor. +---@param sz? number # The z scale factor. +---@param angle? number # The number of radians to rotate around the axis of rotation. +---@param ax? number # The x component of the axis of rotation. +---@param ay? number # The y component of the axis of rotation. +---@param az? number # The z component of the axis of rotation. +function Pass:transform(x, y, z, sx, sy, sz, angle, ax, ay, az) end --- ----ShaderBlocks are objects that can hold large amounts of data and can be sent to Shaders. ---- ----It is common to use "uniform" variables to send data to shaders, but uniforms are usually limited to a few kilobytes in size. ---- ----ShaderBlocks are useful for a few reasons: ---- ----- They can hold a lot more data. ----- Shaders can modify the data in them, which is really useful for compute shaders. ----- Setting the data in a ShaderBlock updates the data for all Shaders using the block, so you ---- don't need to go around setting the same uniforms in lots of different shaders. ---- ----On systems that support compute shaders, ShaderBlocks can optionally be "writable". ---- ----A writable ShaderBlock is a little bit slower than a non-writable one, but shaders can modify its contents and it can be much, much larger than a non-writable ShaderBlock. +---TODO --- --- ---### NOTE: ----- A Shader can use up to 8 ShaderBlocks. ----- ShaderBlocks can not contain textures. ----- Some systems have bugs with `vec3` variables in ShaderBlocks. ---- ----If you run into strange bugs, ---- try switching to a `vec4` for the variable. +---Order matters when scaling, translating, and rotating the coordinate system. --- ----@class lovr.ShaderBlock -local ShaderBlock = {} +---@overload fun(self: lovr.Pass, v: lovr.Vec3) +---@param x? number # The amount to translate on the x axis. +---@param y? number # The amount to translate on the y axis. +---@param z? number # The amount to translate on the z axis. +function Pass:translate(x, y, z) end --- ----Returns the byte offset of a variable in a ShaderBlock. +---TODO --- ----This is useful if you want to manually send binary data to the ShaderBlock using a `Blob` in `ShaderBlock:send`. ---- ----@param field string # The name of the variable to get the offset of. ----@return number offset # The byte offset of the variable. -function ShaderBlock:getOffset(field) end +---@class lovr.Readback +local Readback = {} --- ----Before a ShaderBlock can be used in a Shader, the Shader has to have the block's variables defined in its source code. ---- ----This can be a tedious process, so you can call this function to return a GLSL string that contains this definition. +---Returns the Readback's data as a Blob. --- ----Roughly, it will look something like this: --- ---- layout(std140) uniform <label> { ---- <type> <name>[<count>]; ---- } <namespace>; ---- ----@param label string # The label of the block in the shader code. This will be used to identify it when using `Shader:sendBlock`. ----@param namespace? string # The namespace to use when accessing the block's variables in the shader code. This can be used to prevent naming conflicts if two blocks have variables with the same name. If the namespace is nil, the block's variables will be available in the global scope. ----@return string code # The code that can be prepended to `Shader` code. -function ShaderBlock:getShaderCode(label, namespace) end - ---- ----Returns the size of the ShaderBlock's data, in bytes. ---- ----@return number size # The size of the ShaderBlock, in bytes. -function ShaderBlock:getSize() end - ---- ----Returns the type of the ShaderBlock. +---### NOTE: +---TODO what if it's an image?! --- ----@return lovr.BlockType type # The type of the ShaderBlock. -function ShaderBlock:getType() end +---@return lovr.Blob blob # The Blob. +function Readback:getBlob() end --- ----Returns a variable in the ShaderBlock. +---Returns the data from the Readback, as a table. --- --- ---### NOTE: ----This function is really slow! Only read back values when you need to. ---- ----Vectors and matrices will be returned as (flat) tables. +---TODO what if the readback is a buffer/texture?! --- ----@param name string # The name of the variable to read. ----@return any value # The value of the variable. -function ShaderBlock:read(name) end +---@return table data # A table containing the values that were read back. +function Readback:getData() end --- ----Updates a variable in the ShaderBlock. +---Returns the Readback's data as an Image. --- --- ---### NOTE: ----For scalar or vector types, use tables of numbers or `vec3`s for each vector. +---TODO what if it's a buffer or tally?! --- ----For matrix types, use tables of numbers or `mat4` objects. +---@return lovr.Image image # The Image. +function Readback:getImage() end + --- ----`Blob`s can also be used to pass arbitrary binary data to individual variables. +---Returns whether the Readback has completed on the GPU and its data is available. --- ----@overload fun(self: lovr.ShaderBlock, blob: lovr.Blob, srcOffset?: number, dstOffset?: number, extent?: number):number ----@param variable string # The name of the variable to update. ----@param value any # The new value of the uniform. -function ShaderBlock:send(variable, value) end +---@return boolean complete # Whether the readback is complete. +function Readback:isComplete() end --- ----A Texture is an image that can be applied to `Material`s. +---Blocks the CPU until the Readback is finished on the GPU. --- ----The supported file formats are `.png`, `.jpg`, `.hdr`, `.dds`, `.ktx`, and `.astc`. --- ----DDS and ASTC are compressed formats, which are recommended because they're smaller and faster. +---### NOTE: +---TODO what if the readback will never complete?! --- ----@class lovr.Texture -local Texture = {} +---@return boolean waited # Whether the CPU had to be blocked for waiting. +function Readback:wait() end --- ----Returns the compare mode for the texture. +---TODO --- ----@return lovr.CompareMode compareMode # The current compare mode, or `nil` if none is set. -function Texture:getCompareMode() end +---@class lovr.Sampler +local Sampler = {} --- ----Returns the depth of the Texture, or the number of images stored in the Texture. +---TODO --- ----@param mipmap? number # The mipmap level to get the depth of. This is only valid for volume textures. ----@return number depth # The depth of the Texture. -function Texture:getDepth(mipmap) end +---@return number anisotropy # TODO +function Sampler:getAnisotropy() end --- ----Returns the dimensions of the Texture. +---TODO --- ----@param mipmap? number # The mipmap level to get the dimensions of. ----@return number width # The width of the Texture, in pixels. ----@return number height # The height of the Texture, in pixels. ----@return number depth # The number of images stored in the Texture, for non-2D textures. -function Texture:getDimensions(mipmap) end +---@return lovr.CompareMode compare # TODO +function Sampler:getCompareMode() end --- ----Returns the current FilterMode for the Texture. +---TODO --- ----@return lovr.FilterMode mode # The filter mode for the Texture. ----@return number anisotropy # The level of anisotropic filtering. -function Texture:getFilter() end +---@return lovr.FilterMode min # TODO +---@return lovr.FilterMode mag # TODO +---@return lovr.FilterMode mip # TODO +function Sampler:getFilter() end --- ----Returns the format of the Texture. ---- ----This describes how many color channels are in the texture as well as the size of each one. ---- ----The most common format used is `rgba`, which contains red, green, blue, and alpha color channels. +---TODO --- ----See `TextureFormat` for all of the possible formats. ---- ----@return lovr.TextureFormat format # The format of the Texture. -function Texture:getFormat() end +---@return number min # TODO +---@return number max # TODO +function Sampler:getMipmapRange() end --- ----Returns the height of the Texture. +---TODO --- ----@param mipmap? number # The mipmap level to get the height of. ----@return number height # The height of the Texture, in pixels. -function Texture:getHeight(mipmap) end +---@return lovr.WrapMode x # TODO +---@return lovr.WrapMode y # TODO +---@return lovr.WrapMode z # TODO +function Sampler:getWrap() end --- ----Returns the number of mipmap levels of the Texture. +---TODO --- ----@return number mipmaps # The number of mipmap levels in the Texture. -function Texture:getMipmapCount() end +---@class lovr.Shader +local Shader = {} --- ----Returns the type of the Texture. +---TODO --- ----@return lovr.TextureType type # The type of the Texture. -function Texture:getType() end +---@param source lovr.Shader # The Shader to clone. +---@param flags table # TODO +---@return lovr.Shader shader # The new Shader. +function Shader:clone(source, flags) end --- ----Returns the width of the Texture. +---TODO --- ----@param mipmap? number # The mipmap level to get the width of. ----@return number width # The width of the Texture, in pixels. -function Texture:getWidth(mipmap) end +---@return lovr.ShaderType type # The type of the Shader. +function Shader:getType() end --- ----Returns the current WrapMode for the Texture. +---Returns the workgroup size of a compute shader. --- ----@return lovr.WrapMode horizontal # How the texture wraps horizontally. ----@return lovr.WrapMode vertical # How the texture wraps vertically. -function Texture:getWrap() end - +---TODO what is it. --- ----Replaces pixels in the Texture, sourcing from an `Image` object. ---- ----@param image lovr.Image # The Image containing the pixels to use. Currently, the Image needs to have the same dimensions as the source Texture. ----@param x? number # The x offset to replace at. ----@param y? number # The y offset to replace at. ----@param slice? number # The slice to replace. Not applicable for 2D textures. ----@param mipmap? number # The mipmap to replace. -function Texture:replacePixels(image, x, y, slice, mipmap) end +---@return number x # The x size of a workgroup. +---@return number y # The y size of a workgroup. +---@return number z # The z size of a workgroup. +function Shader:getWorkgroupSize() end --- ----Sets the compare mode for a texture. ---- ----This is only used for "shadow samplers", which are uniform variables in shaders with type `sampler2DShadow`. +---TODO --- ----Sampling a shadow sampler uses a sort of virtual depth test, and the compare mode of the texture is used to control how the depth test is performed. ---- ----@param compareMode? lovr.CompareMode # The new compare mode. Use `nil` to disable the compare mode. -function Texture:setCompareMode(compareMode) end +---@overload fun(self: lovr.Shader, location: number):boolean +---@param name string # The name of an attribute. +---@return boolean exists # Whether the Shader has the attribute. +function Shader:hasAttribute(name) end --- ----Sets the `FilterMode` used by the texture. ---- +---TODO --- ----### NOTE: ----The default setting for new textures can be set with `lovr.graphics.setDefaultFilter`. +---@param stage lovr.ShaderStage # The stage. +---@return boolean exists # Whether the Shader has the stage. +function Shader:hasStage(stage) end + --- ----The maximum supported anisotropy level can be queried using `lovr.graphics.getLimits`. +---TODO --- ----@param mode lovr.FilterMode # The filter mode. ----@param anisotropy number # The level of anisotropy to use. -function Texture:setFilter(mode, anisotropy) end +---@class lovr.Tally +local Tally = {} --- ----Sets the wrap mode of a texture. +---Returns the number of slots in the Tally. --- ----The wrap mode controls how the texture is sampled when texture coordinates lie outside the usual 0 - 1 range. +---@return number count # The number of slots in the Tally. +function Tally:getCount() end + --- ----The default for both directions is `repeat`. +---TODO --- ----@param horizontal lovr.WrapMode # How the texture should wrap horizontally. ----@param vertical? lovr.WrapMode # How the texture should wrap vertically. -function Texture:setWrap(horizontal, vertical) end +---@return lovr.TallyType type # TODO +function Tally:getType() end --- ----Different ways arcs can be drawn with `lovr.graphics.arc`. +---Tally objects with the `time` type can only be used in render passes with a certain number of views. --- ----@alias lovr.ArcMode +---This returns that number. --- ----The arc is drawn with the center of its circle included in the list of points (default). +---@return number views # The number of views the Tally is compatible with. +function Tally:getViewCount() end + --- ----| "pie" +---Textures are multidimensional blocks of memory on the GPU, contrasted with `Buffer`s which are similar but one-dimensional. --- ----The curve of the arc is drawn as a single line. +---Textures can be used to provide material data to Shaders, and they are also used as the destination for rendering operations. --- ----| "open" +---Textures can be created from image filenames, `Image` objects, or they can be left blank and created with a width, height, and depth. --- ----The starting and ending points of the arc's curve are connected. +---Each Texture has a type (`TextureType`). --- ----| "closed" - +---2D Textures are the most common and are often used to store color image data, but there are also cubemaps for skyboxes, 3D textures for volumetric info, and array textures which store a sequence of 2D images. --- ----Here are the different data types available for vertex attributes in a Mesh. +---The format of a Texture (`TextureFormat`) defines the size and number of channels of each pixel. --- ----The ones that have a smaller range take up less memory, which improves performance a bit. +---Textures can have mipmaps, which are a precomputed set of progressively smaller versions of the Texture. --- ----The "u" stands for "unsigned", which means it can't hold negative values but instead has a larger positive range. +---Mipmaps help make the Texture look smoother at smaller sizes, and also improve the performance of reading data from the Texture in a Shader. --- ----@alias lovr.AttributeType +---When used as a render target, the Texture can store multiple different color samples for each pixel, which can be averaged together after rendering to do antialiasing (this is called multisample antialiasing, or MSAA). --- ----A signed 8 bit number, from -128 to 127. +---It is possible to create multiple views of a single Texture. --- ----| "byte" +---A texture view references a subset of the array layers and mipmap levels of its parent texture, and can be bound to a Shader or used as a render target just like a normal texture. --- ----An unsigned 8 bit number, from 0 to 255. +---@class lovr.Texture +local Texture = {} + --- ----| "ubyte" +---Returns the width, height, and depth of the Texture. --- ----A signed 16 bit number, from -32768 to 32767. +---@return number width # The width of the Texture. +---@return number height # The height of the Texture. +---@return number depth # The depth of the Texture. +function Texture:getDimensions() end + --- ----| "short" +---Returns the format of the texture. --- ----An unsigned 16 bit number, from 0 to 65535. +---The default is `rgba8`. --- ----| "ushort" +---@return lovr.TextureFormat format # The format of the Texture. +function Texture:getFormat() end + --- ----A signed 32 bit number, from -2147483648 to 2147483647. +---Returns the height of the Texture, in pixels. --- ----| "int" +---@return number height # The height of the Texture, in pixels. +function Texture:getHeight() end + --- ----An unsigned 32 bit number, from 0 to 4294967295. +---Returns the layer count of the Texture. --- ----| "uint" +---2D textures always have 1 layer and cubemaps always have 6 layers. --- ----A 32 bit floating-point number (large range, but can start to lose precision). +---For 3D and array textures, this is the number of images stored in the texture. 3D textures represent a spatial 3D volume, whereas array textures are multiple layers of distinct 2D images. --- ----| "float" +---@return number layers # The layer count of the Texture. +function Texture:getLayerCount() end --- ----Different ways the alpha channel of pixels affects blending. +---Returns the number of mipmap levels in the Texture. --- +---This is set when the Texture is created. By default, textures are created with a full set of mipmap levels, and mipmaps are generated if the images used to create the texture do not include mipmaps. --- ----### NOTE: ----The premultiplied mode should be used if pixels being drawn have already been blended, or "pre-multiplied", by the alpha channel. ---- ----This happens when rendering a framebuffer that contains pixels with transparent alpha values, since the stored color values have already been faded by alpha and don't need to be faded a second time with the alphamultiply blend mode. --- ----@alias lovr.BlendAlphaMode +---### NOTE: +---Each mipmap level will be half the size of the previous (larger) mipmap level, down to a single pixel. --- ----Color channel values are multiplied by the alpha channel during blending. +---This means the maximum number of mipmap levels is given by `log2(max(width, height))` for non-3D textures and `log2(max(width, height, depth))` for 3D textures. --- ----| "alphamultiply" +---@return number mipmaps # The number of mipmap levels in the Texture. +function Texture:getMipmapCount() end + --- ----Color channels are not multiplied by the alpha channel. +---Returns the parent of a Texture view, which is the Texture that it references. --- ----This should be used if the pixels being drawn have already been blended, or "pre-multiplied", by the alpha channel. +---Returns `nil` if the Texture is not a view. --- ----| "premultiplied" +---@return lovr.Texture parent # The parent of the texture, or `nil` if the texture is not a view. +function Texture:getParent() end --- ----Blend modes control how overlapping pixels are blended together, similar to layers in Photoshop. ---- ----@alias lovr.BlendMode +---Returns the number of multisample antialiasing (MSAA) samples in the Texture. --- ----Normal blending where the alpha value controls how the colors are blended. +---Multisampling is used for antialiasing when rendering to the Texture. --- ----| "alpha" +---Using more samples will cause the Texture to use additional memory but reduce aliasing artifacts. --- ----The incoming pixel color is added to the destination pixel color. --- ----| "add" +---### NOTE: +---Currently, the sample count must be either 1 or 4. --- ----The incoming pixel color is subtracted from the destination pixel color. +---@return number samples # The number of samples in the Texture. +function Texture:getSampleCount() end + --- ----| "subtract" +---Returns the type of the texture. --- ----The color channels from the two pixel values are multiplied together to produce a result. +---@return lovr.TextureType type # The type of the Texture. +function Texture:getType() end + --- ----| "multiply" +---Returns the width of the Texture, in pixels. --- ----The maximum value from each color channel is used, resulting in a lightening effect. +---@return number width # The width of the Texture, in pixels. +function Texture:getWidth() end + --- ----| "lighten" +---Returns whether a Texture was created with a set of `TextureUsage` flags. --- ----The minimum value from each color channel is used, resulting in a darkening effect. +---Usage flags are specified when the Texture is created, and restrict what you can do with a Texture object. --- ----| "darken" +---By default, only the `sample` usage is enabled. --- ----The opposite of multiply: The pixel values are inverted, multiplied, and inverted again, resulting in a lightening effect. +---Applying a smaller set of usage flags helps LÖVR optimize things better. --- ----| "screen" +---@vararg lovr.TextureUsage # One or more usage flags. +---@return boolean supported # Whether the Texture has all the provided usage flags. +function Texture:hasUsage(...) end --- ----There are two types of ShaderBlocks that can be used: `uniform` and `compute`. ---- ----Uniform blocks are read only in shaders, can sometimes be a bit faster than compute blocks, and have a limited size (but the limit will be at least 16KB, you can check `lovr.graphics.getLimits` to check). +---Returns whether a Texture is a texture view, created with `Texture:newView`. --- ----Compute blocks can be written to by compute shaders, might be slightly slower than uniform blocks, and have a much, much larger maximum size. ---- ----@alias lovr.BlockType ---- ----A uniform block. +---@return boolean view # Whether the Texture is a texture view. +function Texture:isView() end + --- ----| "uniform" +---Creates a new Texture view. --- ----A compute block. +---A texture view does not store any pixels on its own, but instead uses the pixel data of a "parent" Texture object. --- ----| "compute" - +---The width, height, format, sample count, and usage flags all match the parent. --- ----This acts as a hint to the graphics driver about what kinds of data access should be optimized for. +---The view may have a different `TextureType` from the parent, and it may reference a subset of the parent texture's images and mipmap levels. --- ----@alias lovr.BufferUsage +---Texture views can be used as render targets in a render pass and they can be bound to Shaders. They can not currently be used for transfer operations. --- ----A buffer that you intend to create once and never modify. +---They are used for: --- ----| "static" +---- Reinterpretation of texture contents. --- ----A buffer which is modified occasionally. +---For example, a cubemap can be treated as +--- an array texture. +---- Rendering to a particular image or mipmap level of a texture. +---- Binding a particular image or mipmap level to a shader. --- ----| "dynamic" +---@param parent lovr.Texture # The parent Texture to create the view of. +---@param type lovr.TextureType # The texture type of the view. +---@param layer? number # The index of the first layer in the view. +---@param layerCount? number # The number of layers in the view, or `nil` to use all remaining layers. +---@param mipmap? number # The index of the first mipmap in the view. +---@param mipmapCount? number # The number of mipmaps in the view, or `nil` to use all remaining mipmaps. +---@return lovr.Texture view # The new texture view. +function Texture:newView(parent, type, layer, layerCount, mipmap, mipmapCount) end + --- ----A buffer which is entirely replaced on the order of every frame. +---The different ways to pack Buffer fields into memory. --- ----| "stream" - +---The default is `packed`, which is suitable for vertex buffers and index buffers. --- ----The method used to compare z values when deciding how to overlap rendered objects. +---It doesn't add any padding between elements, and so it doesn't waste any space. --- ----This is called the "depth test", and it happens on a pixel-by-pixel basis every time new objects are drawn. +---However, this layout won't necessarily work for uniform buffers and storage buffers. --- ----If the depth test "passes" for a pixel, then the pixel color will be replaced by the new color and the depth value in the depth buffer will be updated. +---The `std140` layout corresponds to the std140 layout used for uniform buffers in GLSL. --- ----Otherwise, the pixel will not be changed and the depth value will not be updated. +---It adds the most padding between fields, and requires the stride to be a multiple of 16. --- ----@alias lovr.CompareMode +---Example: --- ----The depth test passes when the depth values are equal. +---``` layout(std140) uniform ObjectScales { float scales[64]; }; ``` --- ----| "equal" +---The `std430` layout corresponds to the std430 layout used for storage buffers in GLSL. --- ----The depth test passes when the depth values are not equal. +---It adds some padding between certain types, and may round up the stride. --- ----| "notequal" +---Example: --- ----The depth test passes when the new depth value is less than the existing one. +---``` layout(std430) buffer TileSizes { vec2 sizes[]; } ``` --- ----| "less" +---@alias lovr.BufferLayout --- ----The depth test passes when the new depth value is less than or equal to the existing one. +---The packed layout, without any padding. --- ----| "lequal" +---| "packed" --- ----The depth test passes when the new depth value is greater than or equal to the existing one. +---The std140 layout. --- ----| "gequal" +---| "std140" --- ----The depth test passes when the new depth value is greater than the existing one. +---The std430 layout. --- ----| "greater" +---| "std430" --- ----Different coordinate spaces for nodes in a Model. +---Different types for `Buffer` fields. --- ----@alias lovr.CoordinateSpace +---These are scalar, vector, or matrix types, usually packed into small amounts of space to reduce the amount of memory they occupy. --- ----The coordinate space relative to the node's parent. +---The names are encoded as follows: --- ----| "local" +---- The data type: +--- - `i` for signed integer +--- - `u` for unsigned integer +--- - `sn` for signed normalized (-1 to 1) +--- - `un` for unsigned normalized (0 to 1) +--- - `f` for floating point +---- The bit depth of each component +---- The letter `x` followed by the component count (for vectors) --- ----The coordinate space relative to the root node of the Model. --- ----| "global" - ---- ----The following shaders are built in to LÖVR, and can be used as an argument to `lovr.graphics.newShader` instead of providing raw GLSL shader code. +---### NOTE: +---In addition to these values, the following aliases can be used: --- ----The shaders can be further customized by using the `flags` argument. +---<table> +--- <thead> +--- <tr> +--- <td>Alias</td> +--- <td>Maps to</td> +--- </tr> +--- </thead> +--- <tbody> +--- <tr> +--- <td><code>vec2</code></td> +--- <td><code>f32x2</code></td> +--- </tr> +--- <tr> +--- <td><code>vec3</code></td> +--- <td><code>f32x3</code></td> +--- </tr> +--- <tr> +--- <td><code>vec4</code></td> +--- <td><code>f32x4</code></td> +--- </tr> +--- <tr> +--- <td><code>int</code></td> +--- <td><code>i32</code></td> +--- </tr> +--- <tr> +--- <td><code>uint</code></td> +--- <td><code>u32</code></td> +--- </tr> +--- <tr> +--- <td><code>float</code></td> +--- <td><code>f32</code></td> +--- </tr> +--- <tr> +--- <td><code>color</code></td> +--- <td><code>un8x4</code></td> +--- </tr> +--- </tbody> </table> --- ----If you pass in `nil` to `lovr.graphics.setShader`, LÖVR will automatically pick a DefaultShader to use based on whatever is being drawn. +---Additionally, the following convenience rules apply: --- ----@alias lovr.DefaultShader +---- Field types can end in an `s`, which will be stripped off. +---- Field types can end in `x1`, which will be stripped off. --- ----A simple shader without lighting, using only colors and a diffuse texture. +---So you can write, e.g. `lovr.graphics.newBuffer(4, 'floats')`, which is cute! --- ----| "unlit" +---@alias lovr.FieldType --- ----A physically-based rendering (PBR) shader, using advanced material properties. +---Four 8-bit signed integers. --- ----| "standard" +---| "i8x4" --- ----A shader that renders a cubemap texture. +---Four 8-bit unsigned integers. --- ----| "cube" +---| "u8x4" --- ----A shader that renders a 2D equirectangular texture with spherical coordinates. +---Four 8-bit signed normalized values. --- ----| "pano" +---| "sn8x4" --- ----A shader that renders font glyphs. +---Four 8-bit unsigned normalized values (aka `color`). --- ----| "font" +---| "un8x4" --- ----A shader that passes its vertex coordinates unmodified to the fragment shader, used to render view-independent fixed geometry like fullscreen quads. +---Three 10-bit unsigned normalized values, and 2 padding bits (aka `normal`). --- ----| "fill" - +---| "un10x3" --- ----Meshes are lists of arbitrary vertices. +---One 16-bit signed integer. --- ----These vertices can be connected in different ways, leading to different shapes like lines and triangles. +---| "i16" --- ----@alias lovr.DrawMode +---Two 16-bit signed integers. --- ----Draw each vertex as a single point. +---| "i16x2" --- ----| "points" +---Four 16-bit signed integers. --- ----The vertices represent a list of line segments. Each pair of vertices will have a line drawn between them. +---| "i16x4" --- ----| "lines" +---One 16-bit unsigned integer. --- ----The first two vertices have a line drawn between them, and each vertex after that will be connected to the previous vertex with a line. +---| "u16" --- ----| "linestrip" +---Two 16-bit unsigned integers. --- ----Similar to linestrip, except the last vertex is connected back to the first. +---| "u16x2" --- ----| "lineloop" +---Four 16-bit unsigned integers. --- ----The first three vertices define a triangle. +---| "u16x4" --- ----Each vertex after that creates a triangle using the new vertex and last two vertices. +---Two 16-bit signed normalized values. --- ----| "strip" +---| "sn16x2" --- ----Each set of three vertices represents a discrete triangle. +---Four 16-bit signed normalized values. --- ----| "triangles" +---| "sn16x4" --- ----Draws a set of triangles. +---Two 16-bit unsigned normalized values. --- ----Each one shares the first vertex as a common point, leading to a fan-like shape. +---| "un16x2" --- ----| "fan" - +---Four 16-bit unsigned normalized values. --- ----Most graphics primitives can be drawn in one of two modes: a filled mode and a wireframe mode. +---| "un16x4" --- ----@alias lovr.DrawStyle +---One 32-bit signed integer (aka `int`). --- ----The shape is drawn as a filled object. +---| "i32" --- ----| "fill" +---Two 32-bit signed integers. --- ----The shape is drawn as a wireframe object. +---| "i32x2" --- ----| "line" - +---Two 32-bit signed integers. --- ----The method used to downsample (or upsample) a texture. +---| "i32x2" --- ----"nearest" can be used for a pixelated effect, whereas "linear" leads to more smooth results. +---Three 32-bit signed integers. --- ----Nearest is slightly faster than linear. +---| "i32x3" --- ----@alias lovr.FilterMode +---Four 32-bit signed integers. --- ----Fast nearest-neighbor sampling. +---| "i32x4" --- ----Leads to a pixelated style. +---One 32-bit unsigned integer (aka `uint`). --- ----| "nearest" +---| "u32" --- ----Smooth pixel sampling. +---Two 32-bit unsigned integers. --- ----| "bilinear" +---| "u32x2" --- ----Smooth pixel sampling, with smooth sampling across mipmap levels. +---Three 32-bit unsigned integers. --- ----| "trilinear" - +---| "u32x3" --- ----Different ways to horizontally align text when using `lovr.graphics.print`. +---Four 32-bit unsigned integers. --- ----@alias lovr.HorizontalAlign +---| "u32x4" --- ----Left aligned lines of text. +---Two 16-bit floating point numbers. --- ----| "left" +---| "f16x2" --- ----Centered aligned lines of text. +---Four 16-bit floating point numbers. --- ----| "center" +---| "f16x4" --- ----Right aligned lines of text. +---One 32-bit floating point number (aka `float`). --- ----| "right" - +---| "f32" --- ----The different types of color parameters `Material`s can hold. +---Two 32-bit floating point numbers (aka `vec2`). --- ----@alias lovr.MaterialColor +---| "f32x2" --- ----The diffuse color. +---Three 32-bit floating point numbers (aka `vec3`). --- ----| "diffuse" +---| "f32x3" --- ----The emissive color. +---Four 32-bit floating point numbers (aka `vec4`). --- ----| "emissive" - +---| "f32x4" --- ----The different types of float parameters `Material`s can hold. +---A 2x2 matrix containing four 32-bit floats. --- ----@alias lovr.MaterialScalar +---| "mat2" --- ----The constant metalness factor. +---A 3x3 matrix containing nine 32-bit floats. --- ----| "metalness" +---| "mat3" --- ----The constant roughness factor. +---A 4x4 matrix containing sixteen 32-bit floats. --- ----| "roughness" +---| "mat4" --- ----The different types of texture parameters `Material`s can hold. +---TODO --- ----@alias lovr.MaterialTexture +---@alias lovr.MeshMode --- ----The diffuse texture. +---TODO --- ----| "diffuse" +---| "points" --- ----The emissive texture. +---TODO --- ----| "emissive" +---| "lines" --- ----The metalness texture. +---TODO --- ----| "metalness" +---| "triangles" + --- ----The roughness texture. +---TODO --- ----| "roughness" +---@alias lovr.PassType --- ----The ambient occlusion texture. +---TODO --- ----| "occlusion" +---| "render" --- ----The normal map. +---TODO --- ----| "normal" +---| "compute" --- ----The environment map, should be specified as a cubemap texture. +---TODO --- ----| "environment" +---| "transfer" --- ----Meshes can have a usage hint, describing how they are planning on being updated. ---- ----Setting the usage hint allows the graphics driver optimize how it handles the data in the Mesh. +---TODO --- ----@alias lovr.MeshUsage +---@alias lovr.ShaderStage --- ----The Mesh contents will rarely change. +---TODO --- ----| "static" +---| "vertex" --- ----The Mesh contents will change often. +---TODO --- ----| "dynamic" +---| "fragment" --- ----The Mesh contents will change constantly, potentially multiple times each frame. +---TODO --- ----| "stream" +---| "compute" --- ----Shaders can be used for either rendering operations or generic compute tasks. ---- ----Graphics shaders are created with `lovr.graphics.newShader` and compute shaders are created with `lovr.graphics.newComputeShader`. ---- ----`Shader:getType` can be used on an existing Shader to figure out what type it is. +---TODO --- ---@alias lovr.ShaderType --- ----A graphics shader. +---TODO --- ---| "graphics" --- ----A compute shader. +---TODO --- ---| "compute" --- ----How to modify pixels in the stencil buffer when using `lovr.graphics.stencil`. ---- ----@alias lovr.StencilAction ---- ----Stencil values will be replaced with a custom value. ---- ----| "replace" ---- ----Stencil values will increment every time they are rendered to. ---- ----| "increment" ---- ----Stencil values will decrement every time they are rendered to. +---TODO --- ----| "decrement" +---@alias lovr.StackType --- ----Similar to `increment`, but the stencil value will be set to 0 if it exceeds 255. +---TODO --- ----| "incrementwrap" ---- ----Similar to `decrement`, but the stencil value will be set to 255 if it drops below 0. ---- ----| "decrementwrap" ---- ----Stencil values will be bitwise inverted every time they are rendered to. ---- ----| "invert" +---| "transform" + +---| "state" --- ----Textures can store their pixels in different formats. ---- ----The set of color channels and the number of bits stored for each channel can differ, allowing Textures to optimize their storage for certain kinds of image formats or rendering techniques. ---- ----@alias lovr.TextureFormat ---- ----Each pixel is 24 bits, or 8 bits for each channel. ---- ----| "rgb" ---- ----Each pixel is 32 bits, or 8 bits for each channel (including alpha). ---- ----| "rgba" +---TODO --- ----An rgba format where the colors occupy 4 bits instead of the usual 8. +---@alias lovr.TallyType --- ----| "rgba4" +---Each slot measures elapsed time in nanoseconds. --- ----Each pixel is 64 bits. Each channel is a 16 bit floating point number. +---| "time" --- ----| "rgba16f" +---Each slot measures the approximate number of pixels affected by rendering. --- ----Each pixel is 128 bits. Each channel is a 32 bit floating point number. +---| "pixel" --- ----| "rgba32f" +---Each slot measures the number of times different shader stages are invoked. --- ----A 16-bit floating point format with a single color channel. +---| "shader" + --- ----| "r16f" +---These are the different ways `Texture` objects can be used. --- ----A 32-bit floating point format with a single color channel. +---These are passed in to `lovr.graphics.isFormatSupported` to see which texture operations are supported by the GPU for a given format. --- ----| "r32f" +---@alias lovr.TextureFeature --- ----A 16-bit floating point format with two color channels. +---The Texture can be sampled (e.g. a `texture2D` or `sampler2D` variable in shaders). --- ----| "rg16f" +---| "sample" --- ----A 32-bit floating point format with two color channels. +---The Texture can be used with a `Sampler` using a `FilterMode` of `linear`. --- ----| "rg32f" +---| "filter" --- ----A 16 bit format with 5-bit color channels and a single alpha bit. +---The Texture can be rendered to by using it as a target in a render `Pass`. --- ----| "rgb5a1" +---| "render" --- ----A 32 bit format with 10-bit color channels and two alpha bits. +---Blending can be enabled when rendering to this format in a render pass. --- ----| "rgb10a2" +---| "blend" --- ----Each pixel is 32 bits, and packs three color channels into 10 or 11 bits each. +---The Texture can be sent to an image variable in shaders (e.g. `image2D`). --- ----| "rg11b10f" +---| "storage" --- ----A 16 bit depth buffer. +---Atomic operations can be used on storage textures with this format. --- ----| "d16" +---| "atomic" --- ----A 32 bit floating point depth buffer. +---Source textures in `Pass:blit` can use this format. --- ----| "d32f" +---| "blitsrc" --- ----A depth buffer with 24 bits for depth and 8 bits for stencil. +---Destination textures in `Pass:blit` can use this format. --- ----| "d24s8" +---| "blitdst" --- ----Different types of Textures. +---Different types of textures. +--- +---Textures are multidimensional blocks of GPU memory, and the texture's type determines how many dimensions there are, and adds some semantics about what the 3rd dimension means. --- ---@alias lovr.TextureType --- ----A 2D texture. +---A single 2D image, the most common type. --- ---| "2d" --- ----A 2D array texture with multiple independent 2D layers. ---- ----| "array" ---- ----A cubemap texture with 6 2D faces. ---- ----| "cube" ---- ----A 3D volumetric texture consisting of multiple 2D layers. ---- ----| "volume" - ---- ----When binding writable resources to shaders using `Shader:sendBlock` and `Shader:sendImage`, an access pattern can be specified as a hint that says whether you plan to read or write to the resource (or both). +---A 3D image, where a sequence of 2D images defines a 3D volume. --- ----Sometimes, LÖVR or the GPU driver can use this hint to get better performance or avoid stalling. +---Each mipmap level of a 3D texture gets smaller in the x, y, and z axes, unlike cubemap and array textures. --- ----@alias lovr.UniformAccess +---| "3d" --- ----The Shader will use the resource in a read-only fashion. +---Six 2D images that define the faces of a cubemap, used for skyboxes or other "directional" images. --- ----| "read" ---- ----The Shader will use the resource in a write-only fashion. ---- ----| "write" ---- ----The resource will be available for reading and writing. ---- ----| "readwrite" - ---- ----Different ways to vertically align text when using `lovr.graphics.print`. ---- ----@alias lovr.VerticalAlign ---- ----Align the top of the text to the origin. ---- ----| "top" ---- ----Vertically center the text. ---- ----| "middle" +---| "cube" --- ----Align the bottom of the text to the origin. +---Array textures are sequences of distinct 2D images. --- ----| "bottom" +---| "array" --- ----Whether the points on triangles are specified in a clockwise or counterclockwise order. ---- ----@alias lovr.Winding +---These are the different things `Texture`s can be used for. --- ----Triangle vertices are specified in a clockwise order. +---When creating a Texture, a set of these flags can be provided, restricting what operations are allowed on the texture. --- ----| "clockwise" +---Using a smaller set of flags may improve performance. --- ----Triangle vertices are specified in a counterclockwise order. +---If none are provided, the only usage flag applied is `sample`. --- ----| "counterclockwise" - +---@alias lovr.TextureUsage --- ----The method used to render textures when texture coordinates are outside of the 0-1 range. +---Whether the texture can be sampled from in Shaders (i.e. used in a material, or bound to a variable with a `texture` type, like `texture2D`). --- ----@alias lovr.WrapMode +---| "sample" --- ----The texture will be clamped at its edges. +---Whether the texture can be rendered to (i.e. by using it as a render target in `lovr.graphics.pass`). --- ----| "clamp" +---| "render" --- ----The texture repeats. +---Whether the texture can be used as a storage texture for compute operations (i.e. bound to a variable with an `image` type, like `image2D`). --- ----| "repeat" +---| "storage" --- ----The texture will repeat, mirroring its appearance each time it repeats. +---Whether the texture can be used in a transfer pass. --- ----| "mirroredrepeat" +---| "transfer" diff --git a/meta/3rd/lovr/library/lovr/headset.lua b/meta/3rd/lovr/library/lovr/headset.lua index fd6e9d63..502d73d6 100644 --- a/meta/3rd/lovr/library/lovr/headset.lua +++ b/meta/3rd/lovr/library/lovr/headset.lua @@ -260,6 +260,12 @@ function lovr.headset.getOrientation(device) end function lovr.headset.getOriginType() end --- +---TODO +--- +---@return lovr.Pass pass # The Pass. +function lovr.headset.getPass() end + +--- ---Returns the current position and orientation of a device. --- --- diff --git a/meta/3rd/lovr/library/lovr/math.lua b/meta/3rd/lovr/library/lovr/math.lua index 43a6004e..3716a6d3 100644 --- a/meta/3rd/lovr/library/lovr/math.lua +++ b/meta/3rd/lovr/library/lovr/math.lua @@ -799,9 +799,11 @@ function Vec2:length() end --- ---A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. --- ----@overload fun(self: lovr.Vec2, x: number, y: number):lovr.Vec2 +---@overload fun(self: lovr.Vec2, x: number, y: number, t: number):lovr.Vec2 +---@param u lovr.Vec2 # The vector to lerp towards. +---@param t number # The lerping parameter. ---@return lovr.Vec2 v # The original vector, containing the new lerped values. -function Vec2:lerp() end +function Vec2:lerp(u, t) end --- ---Multiplies the vector by a vector or a number. |