From b37ebceffe695defd7e7976e653ce127618614c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=80=E8=90=8C=E5=B0=8F=E6=B1=90?= Date: Tue, 22 Feb 2022 17:35:37 +0800 Subject: update love-api --- 3rd/lovr-api | 2 +- meta/3rd/love2d/library/love.graphics.lua | 12 +- meta/3rd/love2d/library/love.lua | 1 + meta/3rd/lovr/library/callback.lua | 116 ++- meta/3rd/lovr/library/lovr.audio.lua | 357 +++++++- meta/3rd/lovr/library/lovr.data.lua | 226 ++++- meta/3rd/lovr/library/lovr.event.lua | 52 +- meta/3rd/lovr/library/lovr.filesystem.lua | 136 ++- meta/3rd/lovr/library/lovr.graphics.lua | 1417 ++++++++++++++++++++++++++--- meta/3rd/lovr/library/lovr.headset.lua | 365 +++++++- meta/3rd/lovr/library/lovr.lua | 22 +- meta/3rd/lovr/library/lovr.math.lua | 341 ++++++- meta/3rd/lovr/library/lovr.physics.lua | 506 ++++++++-- meta/3rd/lovr/library/lovr.system.lua | 8 +- meta/3rd/lovr/library/lovr.thread.lua | 72 +- meta/3rd/lovr/library/lovr.timer.lua | 26 +- tools/love-api.lua | 33 +- tools/lovr-api.lua | 33 +- 18 files changed, 3382 insertions(+), 343 deletions(-) diff --git a/3rd/lovr-api b/3rd/lovr-api index 6f1dab44..8548de84 160000 --- a/3rd/lovr-api +++ b/3rd/lovr-api @@ -1 +1 @@ -Subproject commit 6f1dab44936aeec43d5288af8fdfbd80ddcecb4a +Subproject commit 8548de845c91dfd8639d47018b7d421f857322e0 diff --git a/meta/3rd/love2d/library/love.graphics.lua b/meta/3rd/love2d/library/love.graphics.lua index d2f8c7d8..056cfef1 100644 --- a/meta/3rd/love2d/library/love.graphics.lua +++ b/meta/3rd/love2d/library/love.graphics.lua @@ -92,7 +92,9 @@ function love.graphics.discard(discardcolor, discardstencil) end --- ---The right and bottom edges of the object are shifted at an angle defined by the shearing factors. --- ----When using the default shader anything drawn with this function will be tinted according to the currently selected color. Set it to pure white to preserve the object's original colors. +---When using the default shader anything drawn with this function will be tinted according to the currently selected color. +--- +---Set it to pure white to preserve the object's original colors. --- ---@overload fun(texture: love.Texture, quad: love.Quad, x: number, y: number, r: number, sx: number, sy: number, ox: number, oy: number, kx: number, ky: number) ---@overload fun(drawable: love.Drawable, transform: love.Transform) @@ -418,7 +420,9 @@ function love.graphics.getTextureTypes() end function love.graphics.getWidth() end --- ----Sets the scissor to the rectangle created by the intersection of the specified rectangle with the existing scissor. If no scissor is active yet, it behaves like love.graphics.setScissor. +---Sets the scissor to the rectangle created by the intersection of the specified rectangle with the existing scissor. +--- +---If no scissor is active yet, it behaves like love.graphics.setScissor. --- ---The scissor limits the drawing area to a specified rectangle. This affects all graphics calls, including love.graphics.clear. --- @@ -718,7 +722,9 @@ function love.graphics.present() end --- ---Draws text on screen. If no Font is set, one will be created and set (once) if needed. --- ----As of LOVE 0.7.1, when using translation and scaling functions while drawing text, this function assumes the scale occurs first. If you don't script with this in mind, the text won't be in the right position, or possibly even on screen. +---As of LOVE 0.7.1, when using translation and scaling functions while drawing text, this function assumes the scale occurs first. +--- +---If you don't script with this in mind, the text won't be in the right position, or possibly even on screen. --- ---love.graphics.print and love.graphics.printf both support UTF-8 encoding. You'll also need a proper Font for special characters. --- diff --git a/meta/3rd/love2d/library/love.lua b/meta/3rd/love2d/library/love.lua index c1c55c69..8c2e3f18 100644 --- a/meta/3rd/love2d/library/love.lua +++ b/meta/3rd/love2d/library/love.lua @@ -1,6 +1,7 @@ ---@meta -- version: 11.4 + ---@class love love = {} diff --git a/meta/3rd/lovr/library/callback.lua b/meta/3rd/lovr/library/callback.lua index 3fb0a960..13cbef51 100644 --- a/meta/3rd/lovr/library/callback.lua +++ b/meta/3rd/lovr/library/callback.lua @@ -1,19 +1,47 @@ ---@meta --- ----The `lovr.conf` callback lets you configure default settings for LÖVR. It is called once right before the game starts. Make sure you put `lovr.conf` in a file called `conf.lua`, a special file that's loaded before the rest of the framework initializes. +---The `lovr.conf` callback lets you configure default settings for LÖVR. +--- +---It is called once right before the game starts. +--- +---Make sure you put `lovr.conf` in a file called `conf.lua`, a special file that's loaded before the rest of the framework initializes. +--- +--- +---### NOTE: +---Disabling the headset module can improve startup time a lot if you aren't intending to use `lovr.headset`. +--- +---You can set `t.window` to nil to avoid creating the window. You can do it yourself later by using `lovr.graphics.createWindow`. +--- +---If the `lovr.graphics` module is disabled or the window isn't created, attempting to use any functionality requiring graphics may cause a crash. +--- +---Enabling the `t.graphics.debug` flag will add additional error checks and will send messages from the GPU driver to the `lovr.log` callback. +--- +---This will decrease performance but can help provide information on performance problems or other bugs. +--- +---The `headset.offset` field is a vertical offset applied to the scene for headsets that do not center their tracking origin on the floor. +--- +---This can be thought of as a "default user height". Setting this offset makes it easier to design experiences that work in both seated and standing VR configurations. --- ---@type fun(t: table) lovr.conf = nil --- ----This callback is called every frame. Use it to render the scene. If a VR headset is connected, anything rendered by this function will appear in the headset display. The display is cleared to the background color before this function is called. +---This callback is called every frame. +--- +---Use it to render the scene. +--- +---If a VR headset is connected, anything rendered by this function will appear in the headset display. +--- +---The display is cleared to the background color before this function is called. --- ---@type fun() lovr.draw = nil --- ----The "lovr.errhand" callback is run whenever an error occurs. It receives two parameters. The first is a string containing the error message. The second is either nil, or a string containing a traceback (as returned by "debug.traceback()"); if nil, this means "lovr.errhand" is being called in the stack where the error occurred, and it can call "debug.traceback()" itself. +---The "lovr.errhand" callback is run whenever an error occurs. +--- +---It receives two parameters. The first is a string containing the error message. The second is either nil, or a string containing a traceback (as returned by "debug.traceback()"); if nil, this means "lovr.errhand" is being called in the stack where the error occurred, and it can call "debug.traceback()" itself. --- ---"lovr.errhand" should return a handler function to run in a loop to show the error screen. This handler function is of the same type as the one returned by "lovr.run" and has the same requirements (such as pumping events). If an error occurs while this handler is running, the program will terminate immediately-- "lovr.errhand" will not be given a second chance. Errors which occur inside "lovr.errhand" or in the handler it returns may not be cleanly reported, so be careful. --- @@ -23,7 +51,11 @@ lovr.draw = nil lovr.errhand = nil --- ----The `lovr.focus` callback is called whenever the application acquires or loses focus (for example, when opening or closing the Steam dashboard). The callback receives a single argument, focused, which is a boolean indicating whether or not the application is now focused. It may make sense to pause the game or reduce visual fidelity when the application loses focus. +---The `lovr.focus` callback is called whenever the application acquires or loses focus (for example, when opening or closing the Steam dashboard). +--- +---The callback receives a single argument, focused, which is a boolean indicating whether or not the application is now focused. +--- +---It may make sense to pause the game or reduce visual fidelity when the application loses focus. --- ---@type fun(focused: boolean) lovr.focus = nil @@ -41,35 +73,67 @@ lovr.keypressed = nil lovr.keyreleased = nil --- ----This callback is called once when the app starts. It should be used to perform initial setup work, like loading resources and initializing classes and variables. +---This callback is called once when the app starts. +--- +---It should be used to perform initial setup work, like loading resources and initializing classes and variables. +--- +--- +---### NOTE: +---If the project was loaded from a restart using `lovr.event.restart`, the return value from the previously-run `lovr.restart` callback will be made available to this callback as the `restart` key in the `args` table. +--- +---The `args` table follows the [Lua standard](https://en.wikibooks.org/wiki/Lua_Programming/command_line_parameter). +--- +---The arguments passed in from the shell are put into a global table named `arg` and passed to `lovr.load`, but with indices offset such that the "script" (the project path) is at index 0. +--- +---So all arguments (if any) intended for the project are at successive indices starting with 1, and the executable and its "internal" arguments are in normal order but stored in negative indices. --- ---@type fun(args: table) lovr.load = nil --- ----This callback is called when a message is logged. The default implementation of this callback prints the message to the console using `print`, but it's possible to override this callback to render messages in VR, write them to a file, filter messages, and more. +---This callback is called when a message is logged. +--- +---The default implementation of this callback prints the message to the console using `print`, but it's possible to override this callback to render messages in VR, write them to a file, filter messages, and more. --- ---The message can have a "tag" that is a short string representing the sender, and a "level" indicating how severe the message is. --- ----The `t.graphics.debug` flag in `lovr.conf` can be used to get log messages from the GPU driver (tagged as `GL`). It is also possible to emit your own log messages using `lovr.event.push`. +---The `t.graphics.debug` flag in `lovr.conf` can be used to get log messages from the GPU driver (tagged as `GL`). +--- +---It is also possible to emit your own log messages using `lovr.event.push`. --- ---@type fun(message: string, level: string, tag: string) lovr.log = nil --- ----This callback is called every frame after rendering to the headset and is usually used to render a mirror of the headset display onto the desktop window. It can be overridden for custom mirroring behavior. For example, you could render a single eye instead of a stereo view, apply postprocessing effects, add 2D UI, or render the scene from an entirely different viewpoint for a third person camera. +---This callback is called every frame after rendering to the headset and is usually used to render a mirror of the headset display onto the desktop window. +--- +---It can be overridden for custom mirroring behavior. +--- +---For example, you could render a single eye instead of a stereo view, apply postprocessing effects, add 2D UI, or render the scene from an entirely different viewpoint for a third person camera. +--- +--- +---### NOTE: +---When this callback is called, the camera is located at `(0, 0, 0)` and is looking down the negative-z axis. +--- +---Note that the usual graphics state applies while `lovr.mirror` is invoked, so you may need to reset graphics state at the end of `lovr.draw` to get the result you want. --- ---@type fun() lovr.mirror = nil --- ----This callback contains a permission response previously requested with `lovr.system.requestPermission`. The callback contains information on whether permission was granted or denied. +---This callback contains a permission response previously requested with `lovr.system.requestPermission`. +--- +---The callback contains information on whether permission was granted or denied. --- ---@type fun(permission: lovr.Permission, granted: boolean) lovr.permission = nil --- ----This callback is called right before the application is about to quit. Use it to perform any necessary cleanup work. A truthy value can be returned from this callback to abort quitting. +---This callback is called right before the application is about to quit. +--- +---Use it to perform any necessary cleanup work. +--- +---A truthy value can be returned from this callback to abort quitting. --- ---@type fun():boolean lovr.quit = nil @@ -81,13 +145,23 @@ lovr.quit = nil lovr.resize = nil --- ----This callback is called when a restart from `lovr.event.restart` is happening. A value can be returned to send it to the next LÖVR instance, available as the `restart` key in the argument table passed to `lovr.load`. Object instances can not be used as the restart value, since they are destroyed as part of the cleanup process. +---This callback is called when a restart from `lovr.event.restart` is happening. +--- +---A value can be returned to send it to the next LÖVR instance, available as the `restart` key in the argument table passed to `lovr.load`. +--- +---Object instances can not be used as the restart value, since they are destroyed as part of the cleanup process. +--- +--- +---### NOTE: +---Only nil, booleans, numbers, and strings are supported types for the return value. --- ---@type fun():any lovr.restart = nil --- ----This callback is the main entry point for a LÖVR program. It is responsible for calling `lovr.load` and returning the main loop function. +---This callback is the main entry point for a LÖVR program. +--- +---It is responsible for calling `lovr.load` and returning the main loop function. --- ---@type fun():function lovr.run = nil @@ -97,11 +171,21 @@ lovr.run = nil --- ---For example, when `shift + 1` is pressed on an American keyboard, `lovr.textinput` will be called with `!`. --- +--- +---### NOTE: +---Some characters in UTF-8 unicode take multiple bytes to encode. +--- +---Due to the way Lua works, the length of these strings will be bigger than 1 even though they are just a single character. `lovr.graphics.print` is compatible with UTF-8 but doing other string processing on these strings may require a library. +--- +---Lua 5.3+ has support for working with UTF-8 strings. +--- ---@type fun(text: string, code: number) lovr.textinput = nil --- ----The `lovr.threaderror` callback is called whenever an error occurs in a Thread. It receives the Thread object where the error occurred and an error message. +---The `lovr.threaderror` callback is called whenever an error occurs in a Thread. +--- +---It receives the Thread object where the error occurred and an error message. --- ---The default implementation of this callback will call `lovr.errhand` with the error. --- @@ -109,7 +193,11 @@ lovr.textinput = nil lovr.threaderror = nil --- ----The `lovr.update` callback should be used to update your game's logic. It receives a single parameter, `dt`, which represents the amount of elapsed time between frames. You can use this value to scale timers, physics, and animations in your game so they play at a smooth, consistent speed. +---The `lovr.update` callback should be used to update your game's logic. +--- +---It receives a single parameter, `dt`, which represents the amount of elapsed time between frames. +--- +---You can use this value to scale timers, physics, and animations in your game so they play at a smooth, consistent speed. --- ---@type fun(dt: number) lovr.update = nil diff --git a/meta/3rd/lovr/library/lovr.audio.lua b/meta/3rd/lovr/library/lovr.audio.lua index a768b708..71717874 100644 --- a/meta/3rd/lovr/library/lovr.audio.lua +++ b/meta/3rd/lovr/library/lovr.audio.lua @@ -1,13 +1,31 @@ ---@meta --- ----The `lovr.audio` module is responsible for playing sound effects and music. To play a sound, create a `Source` object and call `Source:play` on it. Currently ogg, wav, and mp3 audio formats are supported. +---The `lovr.audio` module is responsible for playing sound effects and music. +--- +---To play a sound, create a `Source` object and call `Source:play` on it. +--- +---Currently ogg, wav, and mp3 audio formats are supported. --- ---@class lovr.audio lovr.audio = {} --- ----Returns the global air absorption coefficients for the medium. This affects Sources that have the `absorption` effect enabled, causing audio volume to drop off with distance as it is absorbed by the medium it's traveling through (air, water, etc.). The difference between absorption and falloff is that absorption is more subtle and is frequency-dependent, so higher-frequency bands can get absorbed more quickly than lower ones. This can be used to apply "underwater" effects and stuff. +---Returns the global air absorption coefficients for the medium. +--- +---This affects Sources that have the `absorption` effect enabled, causing audio volume to drop off with distance as it is absorbed by the medium it's traveling through (air, water, etc.). +--- +---The difference between absorption and falloff is that absorption is more subtle and is frequency-dependent, so higher-frequency bands can get absorbed more quickly than lower ones. +--- +---This can be used to apply "underwater" effects and stuff. +--- +--- +---### NOTE: +---Absorption is currently only supported by the phonon spatializer. +--- +---The frequency bands correspond to `400Hz`, `2.5KHz`, and `15KHz`. +--- +---The default coefficients are `.0002`, `.0017`, and `.0182` for low, mid, and high. --- ---@return number low # The absorption coefficient for the low frequency band. ---@return number mid # The absorption coefficient for the mid frequency band. @@ -15,7 +33,9 @@ lovr.audio = {} function lovr.audio.getAbsorption() end --- ----Returns a list of playback or capture devices. Each device has an `id`, `name`, and a `default` flag indicating whether it's the default device. +---Returns a list of playback or capture devices. +--- +---Each device has an `id`, `name`, and a `default` flag indicating whether it's the default device. --- ---To use a specific device id for playback or capture, pass it to `lovr.audio.setDevice`. --- @@ -55,13 +75,91 @@ function lovr.audio.getPosition() end --- ---Returns the name of the active spatializer (`simple`, `oculus`, or `phonon`). --- ----The `t.audio.spatializer` setting in `lovr.conf` can be used to express a preference for a particular spatializer. If it's `nil`, all spatializers will be tried in the following order: `phonon`, `oculus`, `simple`. +---The `t.audio.spatializer` setting in `lovr.conf` can be used to express a preference for a particular spatializer. +--- +---If it's `nil`, all spatializers will be tried in the following order: `phonon`, `oculus`, `simple`. +--- +--- +---### NOTE: +---Using a feature or effect that is not supported by the current spatializer will not error, it just won't do anything. +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +---
Featuresimplephononoculus
Effect: Spatializationxxx
Effect: Attenuationxx
Effect: Absorptionx
Effect: Occlusionx
Effect: Transmissionx
Effect: Reverbx
lovr.audio.setGeometryx
Source:setDirectivityxx
Source:setRadiusx
--- ---@return string spatializer # The name of the active spatializer. function lovr.audio.getSpatializer() end --- ----Returns the master volume. All audio sent to the playback device has its volume multiplied by this factor. +---Returns the master volume. +--- +---All audio sent to the playback device has its volume multiplied by this factor. +--- +--- +---### NOTE: +---The default volume is 1.0 (0 dB). --- ---@param units? lovr.VolumeUnit # The units to return (linear or db). ---@return number volume # The master volume. @@ -85,7 +183,21 @@ function lovr.audio.isStarted(type) end function lovr.audio.newSource(filename, options) end --- ----Sets the global air absorption coefficients for the medium. This affects Sources that have the `absorption` effect enabled, causing audio volume to drop off with distance as it is absorbed by the medium it's traveling through (air, water, etc.). The difference between absorption and falloff is that absorption is more subtle and is frequency-dependent, so higher-frequency bands can get absorbed more quickly than lower ones. This can be used to apply "underwater" effects and stuff. +---Sets the global air absorption coefficients for the medium. +--- +---This affects Sources that have the `absorption` effect enabled, causing audio volume to drop off with distance as it is absorbed by the medium it's traveling through (air, water, etc.). +--- +---The difference between absorption and falloff is that absorption is more subtle and is frequency-dependent, so higher-frequency bands can get absorbed more quickly than lower ones. +--- +---This can be used to apply "underwater" effects and stuff. +--- +--- +---### NOTE: +---Absorption is currently only supported by the phonon spatializer. +--- +---The frequency bands correspond to `400Hz`, `2.5KHz`, and `15KHz`. +--- +---The default coefficients are `.0002`, `.0017`, and `.0182` for low, mid, and high. --- ---@param low number # The absorption coefficient for the low frequency band. ---@param mid number # The absorption coefficient for the mid frequency band. @@ -95,13 +207,25 @@ function lovr.audio.setAbsorption(low, mid, high) end --- ---Switches either the playback or capture device to a new one. --- ----If a device for the given type is already active, it will be stopped and destroyed. The new device will not be started automatically, use `lovr.audio.start` to start it. +---If a device for the given type is already active, it will be stopped and destroyed. +--- +---The new device will not be started automatically, use `lovr.audio.start` to start it. --- ---A device id (previously retrieved using `lovr.audio.getDevices`) can be given to use a specific audio device, or `nil` can be used for the id to use the default audio device. --- ----A sink can be also be provided when changing the device. A sink is an audio stream (`Sound` object with a `stream` type) that will receive all audio samples played (for playback) or all audio samples captured (for capture). When an audio device with a sink is started, be sure to periodically call `Sound:read` on the sink to read audio samples from it, otherwise it will overflow and discard old data. The sink can have any format, data will be converted as needed. Using a sink for the playback device will reduce performance, but this isn't the case for capture devices. +---A sink can be also be provided when changing the device. +--- +---A sink is an audio stream (`Sound` object with a `stream` type) that will receive all audio samples played (for playback) or all audio samples captured (for capture). --- ----Audio devices can be started in `shared` or `exclusive` mode. Exclusive devices may have lower latency than shared devices, but there's a higher chance that requesting exclusive access to an audio device will fail (either because it isn't supported or allowed). One strategy is to first try the device in exclusive mode, switching to shared if it doesn't work. +---When an audio device with a sink is started, be sure to periodically call `Sound:read` on the sink to read audio samples from it, otherwise it will overflow and discard old data. +--- +---The sink can have any format, data will be converted as needed. Using a sink for the playback device will reduce performance, but this isn't the case for capture devices. +--- +---Audio devices can be started in `shared` or `exclusive` mode. +--- +---Exclusive devices may have lower latency than shared devices, but there's a higher chance that requesting exclusive access to an audio device will fail (either because it isn't supported or allowed). +--- +---One strategy is to first try the device in exclusive mode, switching to shared if it doesn't work. --- ---@param type? lovr.AudioType # The device to switch. ---@param id? userdata # The id of the device to use, or `nil` to use the default device. @@ -111,10 +235,26 @@ function lovr.audio.setAbsorption(low, mid, high) end function lovr.audio.setDevice(type, id, sink, mode) end --- ----Sets a mesh of triangles to use for modeling audio effects, using a table of vertices or a Model. When the appropriate effects are enabled, audio from `Source` objects will correctly be occluded by walls and bounce around to create realistic reverb. +---Sets a mesh of triangles to use for modeling audio effects, using a table of vertices or a Model. +--- +---When the appropriate effects are enabled, audio from `Source` objects will correctly be occluded by walls and bounce around to create realistic reverb. --- ---An optional `AudioMaterial` may be provided to specify the acoustic properties of the geometry. --- +--- +---### NOTE: +---This is currently only supported/used by the `phonon` spatializer. +--- +---The `Effect`s that use geometry are: +--- +---- `occlusion` +---- `reverb` +---- `transmission` +--- +---If an existing geometry has been set, this function will replace it. +--- +---The triangles must use counterclockwise winding. +--- ---@overload fun(model: lovr.Model, material: lovr.AudioMaterial):boolean ---@param vertices table # A flat table of vertices. Each vertex is 3 numbers representing its x, y, and z position. The units used for audio coordinates are up to you, but meters are recommended. ---@param indices table # A list of indices, indicating how the vertices are connected into triangles. Indices are 1-indexed and are 32 bits (they can be bigger than 65535). @@ -152,41 +292,80 @@ function lovr.audio.setPose(x, y, z, angle, ax, ay, az) end function lovr.audio.setPosition(x, y, z) end --- ----Sets the master volume. All audio sent to the playback device has its volume multiplied by this factor. +---Sets the master volume. +--- +---All audio sent to the playback device has its volume multiplied by this factor. +--- +--- +---### NOTE: +---The volume will be clamped to a 0-1 range (0 dB). --- ---@param volume number # The master volume. ---@param units? lovr.VolumeUnit # The units of the value. function lovr.audio.setVolume(volume, units) end --- ----Starts the active playback or capture device. By default the playback device is initialized and started, but this can be controlled using the `t.audio.start` flag in `lovr.conf`. +---Starts the active playback or capture device. +--- +---By default the playback device is initialized and started, but this can be controlled using the `t.audio.start` flag in `lovr.conf`. +--- +--- +---### NOTE: +---Starting an audio device may fail if: +--- +---- The device is already started +---- No device was initialized with `lovr.audio.setDevice` +---- Lack of `audiocapture` permission on Android (see `lovr.system.requestPermission`) +---- Some other problem accessing the audio device --- ---@param type? lovr.AudioType # The type of device to start. ---@return boolean started # Whether the device was successfully started. function lovr.audio.start(type) end --- ----Stops the active playback or capture device. This may fail if: +---Stops the active playback or capture device. +--- +---This may fail if: --- ---- The device is not started ---- No device was initialized with `lovr.audio.setDevice` --- +--- +---### NOTE: +---Switching devices with `lovr.audio.setDevice` will stop the existing one. +--- ---@param type? lovr.AudioType # The type of device to stop. ---@return boolean stopped # Whether the device was successfully stopped. function lovr.audio.stop(type) end --- ----A Source is an object representing a single sound. Currently ogg, wav, and mp3 formats are supported. +---A Source is an object representing a single sound. +--- +---Currently ogg, wav, and mp3 formats are supported. +--- +---When a Source is playing, it will send audio to the speakers. +--- +---Sources do not play automatically when they are created. --- ----When a Source is playing, it will send audio to the speakers. Sources do not play automatically when they are created. Instead, the `play`, `pause`, and `stop` functions can be used to control when they should play. +---Instead, the `play`, `pause`, and `stop` functions can be used to control when they should play. --- ----`Source:seek` and `Source:tell` can be used to control the playback position of the Source. A Source can be set to loop when it reaches the end using `Source:setLooping`. +---`Source:seek` and `Source:tell` can be used to control the playback position of the Source. +--- +---A Source can be set to loop when it reaches the end using `Source:setLooping`. --- ---@class lovr.Source local Source = {} --- ----Creates a copy of the Source, referencing the same `Sound` object and inheriting all of the settings of this Source. However, it will be created in the stopped state and will be rewound to the beginning. +---Creates a copy of the Source, referencing the same `Sound` object and inheriting all of the settings of this Source. +--- +---However, it will be created in the stopped state and will be rewound to the beginning. +--- +--- +---### NOTE: +---This is a good way to create multiple Sources that play the same sound, since the audio data won't be loaded multiple times and can just be reused. +--- +---You can also create multiple `Source` objects and pass in the same `Sound` object for each one, which will have the same effect. --- ---@return lovr.Source source # A genetically identical copy of the Source. function Source:clone() end @@ -196,9 +375,21 @@ function Source:clone() end --- ---The directivity is controlled by two parameters: the weight and the power. --- ----The weight is a number between 0 and 1 controlling the general "shape" of the sound emitted. 0.0 results in a completely omnidirectional sound that can be heard from all directions. 1.0 results in a full dipole shape that can be heard only from the front and back. 0.5 results in a cardioid shape that can only be heard from one direction. Numbers in between will smoothly transition between these. +---The weight is a number between 0 and 1 controlling the general "shape" of the sound emitted. 0.0 results in a completely omnidirectional sound that can be heard from all directions. +--- +---1.0 results in a full dipole shape that can be heard only from the front and back. +--- +---0.5 results in a cardioid shape that can only be heard from one direction. +--- +---Numbers in between will smoothly transition between these. +--- +---The power is a number that controls how "focused" or sharp the shape is. +--- +---Lower power values can be heard from a wider set of angles. --- ----The power is a number that controls how "focused" or sharp the shape is. Lower power values can be heard from a wider set of angles. It is an exponent, so it can get arbitrarily large. Note that a power of zero will still result in an omnidirectional source, regardless of the weight. +---It is an exponent, so it can get arbitrarily large. +--- +---Note that a power of zero will still result in an omnidirectional source, regardless of the weight. --- ---@return number weight # The dipole weight. 0.0 is omnidirectional, 1.0 is a dipole, 0.5 is cardioid. ---@return number power # The dipole power, controlling how focused the directivity shape is. @@ -233,7 +424,9 @@ function Source:getOrientation() end function Source:getPose() end --- ----Returns the position of the Source, in meters. Setting the position will cause the Source to be distorted and attenuated based on its position relative to the listener. +---Returns the position of the Source, in meters. +--- +---Setting the position will cause the Source to be distorted and attenuated based on its position relative to the listener. --- ---@return number x # The x coordinate. ---@return number y # The y coordinate. @@ -243,13 +436,23 @@ function Source:getPosition() end --- ---Returns the radius of the Source, in meters. --- ----This does not control falloff or attenuation. It is only used for smoothing out occlusion. If a Source doesn't have a radius, then when it becomes occluded by a wall its volume will instantly drop. Giving the Source a radius that approximates its emitter's size will result in a smooth transition between audible and occluded, improving realism. +---This does not control falloff or attenuation. +--- +---It is only used for smoothing out occlusion. +--- +---If a Source doesn't have a radius, then when it becomes occluded by a wall its volume will instantly drop. +--- +---Giving the Source a radius that approximates its emitter's size will result in a smooth transition between audible and occluded, improving realism. --- ---@return number radius # The radius of the Source, in meters. function Source:getRadius() end --- ----Returns the `Sound` object backing the Source. Multiple Sources can share one Sound, allowing its data to only be loaded once. An easy way to do this sharing is by using `Source:clone`. +---Returns the `Sound` object backing the Source. +--- +---Multiple Sources can share one Sound, allowing its data to only be loaded once. +--- +---An easy way to do this sharing is by using `Source:clone`. --- ---@return lovr.Sound sound # The Sound object. function Source:getSound() end @@ -264,6 +467,18 @@ function Source:getVolume(units) end --- ---Returns whether a given `Effect` is enabled for the Source. --- +--- +---### NOTE: +---The active spatializer will determine which effects are supported. +--- +---If an unsupported effect is enabled on a Source, no error will be reported. +--- +---Instead, it will be silently ignored. +--- +---See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer. +--- +---Calling this function on a Source that was created with `{ effects = false }` will always return false. +--- ---@param effect lovr.Effect # The effect. ---@return boolean enabled # Whether the effect is enabled. function Source:isEffectEnabled(effect) end @@ -281,12 +496,22 @@ function Source:isLooping() end function Source:isPlaying() end --- ----Pauses the source. It can be resumed with `Source:resume` or `Source:play`. If a paused source is rewound, it will remain paused. +---Pauses the source. +--- +---It can be resumed with `Source:resume` or `Source:play`. If a paused source is rewound, it will remain paused. --- function Source:pause() end --- ----Plays the Source. This doesn't do anything if the Source is already playing. +---Plays the Source. +--- +---This doesn't do anything if the Source is already playing. +--- +--- +---### NOTE: +---There is a maximum of 64 Sources that can be playing at once. +--- +---If 64 Sources are already playing, this function will return `false`. --- ---@return boolean success # Whether the Source successfully started playing. function Source:play() end @@ -294,6 +519,10 @@ function Source:play() end --- ---Seeks the Source to the specified position. --- +--- +---### NOTE: +---Seeking a Source backed by a stream `Sound` has no meaningful effect. +--- ---@param position number # The position to seek to. ---@param unit? lovr.TimeUnit # The units for the seek position. function Source:seek(position, unit) end @@ -303,9 +532,21 @@ function Source:seek(position, unit) end --- ---The directivity is controlled by two parameters: the weight and the power. --- ----The weight is a number between 0 and 1 controlling the general "shape" of the sound emitted. 0.0 results in a completely omnidirectional sound that can be heard from all directions. 1.0 results in a full dipole shape that can be heard only from the front and back. 0.5 results in a cardioid shape that can only be heard from one direction. Numbers in between will smoothly transition between these. +---The weight is a number between 0 and 1 controlling the general "shape" of the sound emitted. 0.0 results in a completely omnidirectional sound that can be heard from all directions. +--- +---1.0 results in a full dipole shape that can be heard only from the front and back. --- ----The power is a number that controls how "focused" or sharp the shape is. Lower power values can be heard from a wider set of angles. It is an exponent, so it can get arbitrarily large. Note that a power of zero will still result in an omnidirectional source, regardless of the weight. +---0.5 results in a cardioid shape that can only be heard from one direction. +--- +---Numbers in between will smoothly transition between these. +--- +---The power is a number that controls how "focused" or sharp the shape is. +--- +---Lower power values can be heard from a wider set of angles. +--- +---It is an exponent, so it can get arbitrarily large. +--- +---Note that a power of zero will still result in an omnidirectional source, regardless of the weight. --- ---@param weight number # The dipole weight. 0.0 is omnidirectional, 1.0 is a dipole, 0.5 is cardioid. ---@param power number # The dipole power, controlling how focused the directivity shape is. @@ -314,6 +555,18 @@ function Source:setDirectivity(weight, power) end --- ---Enables or disables an effect on the Source. --- +--- +---### NOTE: +---The active spatializer will determine which effects are supported. +--- +---If an unsupported effect is enabled on a Source, no error will be reported. +--- +---Instead, it will be silently ignored. +--- +---See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer. +--- +---Calling this function on a Source that was created with `{ effects = false }` will throw an error. +--- ---@param effect lovr.Effect # The effect. ---@param enable boolean # Whether the effect should be enabled. function Source:setEffectEnabled(effect, enable) end @@ -321,6 +574,10 @@ function Source:setEffectEnabled(effect, enable) end --- ---Sets whether or not the Source loops. --- +--- +---### NOTE: +---Attempting to loop a Source backed by a stream `Sound` will cause an error. +--- ---@param loop boolean # Whether or not the Source will loop. function Source:setLooping(loop) end @@ -346,9 +603,13 @@ function Source:setOrientation(angle, ax, ay, az) end function Source:setPose(x, y, z, angle, ax, ay, az) end --- ----Sets the position of the Source, in meters. Setting the position will cause the Source to be distorted and attenuated based on its position relative to the listener. +---Sets the position of the Source, in meters. +--- +---Setting the position will cause the Source to be distorted and attenuated based on its position relative to the listener. --- ----Only mono sources can be positioned. Setting the position of a stereo Source will cause an error. +---Only mono sources can be positioned. +--- +---Setting the position of a stereo Source will cause an error. --- ---@param x number # The x coordinate. ---@param y number # The y coordinate. @@ -358,7 +619,13 @@ function Source:setPosition(x, y, z) end --- ---Sets the radius of the Source, in meters. --- ----This does not control falloff or attenuation. It is only used for smoothing out occlusion. If a Source doesn't have a radius, then when it becomes occluded by a wall its volume will instantly drop. Giving the Source a radius that approximates its emitter's size will result in a smooth transition between audible and occluded, improving realism. +---This does not control falloff or attenuation. +--- +---It is only used for smoothing out occlusion. +--- +---If a Source doesn't have a radius, then when it becomes occluded by a wall its volume will instantly drop. +--- +---Giving the Source a radius that approximates its emitter's size will result in a smooth transition between audible and occluded, improving realism. --- ---@param radius number # The new radius of the Source, in meters. function Source:setRadius(radius) end @@ -366,6 +633,10 @@ function Source:setRadius(radius) end --- ---Sets the current volume factor for the Source. --- +--- +---### NOTE: +---The volume will be clamped to a 0-1 range (0 dB). +--- ---@param volume number # The new volume. ---@param units? lovr.VolumeUnit # The units of the value. function Source:setVolume(volume, units) end @@ -378,6 +649,10 @@ function Source:stop() end --- ---Returns the current playback position of the Source. --- +--- +---### NOTE: +---The return value for Sources backed by a stream `Sound` has no meaning. +--- ---@param unit? lovr.TimeUnit # The unit to return. ---@return number position # The current playback position. function Source:tell(unit) end @@ -406,15 +681,23 @@ function Source:tell(unit) end ---Concrete. --- ---| '"concrete"' + ---| '"glass"' + ---| '"gravel"' + ---| '"metal"' + ---| '"plaster"' + ---| '"rock"' + ---| '"wood"' --- ----Audio devices can be created in shared mode or exclusive mode. In exclusive mode, the audio device is the only one active on the system, which gives better performance and lower latency. However, exclusive devices aren't always supported and might not be allowed, so there is a higher chance that creating one will fail. +---Audio devices can be created in shared mode or exclusive mode. +--- +---In exclusive mode, the audio device is the only one active on the system, which gives better performance and lower latency. However, exclusive devices aren't always supported and might not be allowed, so there is a higher chance that creating one will fail. --- ---@alias lovr.AudioShareMode --- @@ -442,6 +725,16 @@ function Source:tell(unit) end --- ---Different types of effects that can be applied with `Source:setEffectEnabled`. --- +--- +---### NOTE: +---The active spatializer will determine which effects are supported. +--- +---If an unsupported effect is enabled on a Source, no error will be reported. +--- +---Instead, it will be silently ignored. +--- +---TODO: expose a table of supported effects for spatializers in docs or from Lua. +--- ---@alias lovr.Effect --- ---Models absorption as sound travels through the air, water, etc. @@ -469,7 +762,9 @@ function Source:tell(unit) end ---| '"transmission"' --- ----When figuring out how long a Source is or seeking to a specific position in the sound file, units can be expressed in terms of seconds or in terms of frames. A frame is one set of samples for each channel (one sample for mono, two samples for stereo). +---When figuring out how long a Source is or seeking to a specific position in the sound file, units can be expressed in terms of seconds or in terms of frames. +--- +---A frame is one set of samples for each channel (one sample for mono, two samples for stereo). --- ---@alias lovr.TimeUnit --- diff --git a/meta/3rd/lovr/library/lovr.data.lua b/meta/3rd/lovr/library/lovr.data.lua index 9c34b189..a699a2f3 100644 --- a/meta/3rd/lovr/library/lovr.data.lua +++ b/meta/3rd/lovr/library/lovr.data.lua @@ -17,7 +17,17 @@ lovr.data = {} function lovr.data.newBlob(size, name) end --- ----Creates a new Image. Image data can be loaded and decoded from an image file, or a raw block of pixels with a specified width, height, and format can be created. +---Creates a new Image. +--- +---Image data can be loaded and decoded from an image file, or a raw block of pixels with a specified width, height, and format can be created. +--- +--- +---### NOTE: +---The supported image file formats are png, jpg, hdr, dds (DXT1, DXT3, DXT5), ktx, and astc. +--- +---Only 2D textures are supported for DXT/ASTC. +--- +---Currently textures loaded as KTX need to be in DXT/ASTC formats. --- ---@overload fun(width: number, height: number, format: lovr.TextureFormat, data: lovr.Blob):lovr.Image ---@overload fun(source: lovr.Image):lovr.Image @@ -28,7 +38,9 @@ function lovr.data.newBlob(size, name) end function lovr.data.newImage(filename, flip) end --- ----Loads a 3D model from a file. The supported 3D file formats are OBJ and glTF. +---Loads a 3D model from a file. +--- +---The supported 3D file formats are OBJ and glTF. --- ---@overload fun(blob: lovr.Blob):lovr.ModelData ---@param filename string # The filename of the model to load. @@ -45,11 +57,43 @@ function lovr.data.newModelData(filename) end function lovr.data.newRasterizer(size) end --- ----Creates a new Sound. A sound can be loaded from an audio file, or it can be created empty with capacity for a certain number of audio frames. +---Creates a new Sound. +--- +---A sound can be loaded from an audio file, or it can be created empty with capacity for a certain number of audio frames. --- ---When loading audio from a file, use the `decode` option to control whether compressed audio should remain compressed or immediately get decoded to raw samples. --- ----When creating an empty sound, the `contents` parameter can be set to `'stream'` to create an audio stream. On streams, `Sound:setFrames` will always write to the end of the stream, and `Sound:getFrames` will always read the oldest samples from the beginning. The number of frames in the sound is the total capacity of the stream's buffer. +---When creating an empty sound, the `contents` parameter can be set to `'stream'` to create an audio stream. +--- +---On streams, `Sound:setFrames` will always write to the end of the stream, and `Sound:getFrames` will always read the oldest samples from the beginning. +--- +---The number of frames in the sound is the total capacity of the stream's buffer. +--- +--- +---### NOTE: +---It is highly recommended to use an audio format that matches the format of the audio module: `f32` sample formats at a sample rate of 48000, with 1 channel for spatialized sources or 2 channels for unspatialized sources. +--- +---This will avoid the need to convert audio during playback, which boosts performance of the audio thread. +--- +---The WAV importer supports 16, 24, and 32 bit integer data and 32 bit floating point data. +--- +---The data must be mono, stereo, or 4-channel full-sphere ambisonic. +--- +---The `WAVE_FORMAT_EXTENSIBLE` extension is supported. +--- +---Ambisonic channel layouts are supported for import (but not yet for playback). +--- +---Ambisonic data can be loaded from WAV files. +--- +---It must be first-order full-sphere ambisonic data with 4 channels. +--- +---If the WAV has a `WAVE_FORMAT_EXTENSIBLE` chunk with an `AMBISONIC_B_FORMAT` format GUID, then the data is understood as using the AMB format with Furse-Malham channel ordering and normalization. +--- +---*All other* 4-channel files are assumed to be using the AmbiX format with ACN channel ordering and SN3D normalization. +--- +---AMB files will get automatically converted to AmbiX on import, so ambisonic Sounds will always be in a consistent format. +--- +---OGG and MP3 files will always have the `f32` format when loaded. --- ---@overload fun(filename: string, decode: boolean):lovr.Sound ---@overload fun(blob: lovr.Blob, decode: boolean):lovr.Sound @@ -62,7 +106,11 @@ function lovr.data.newRasterizer(size) end function lovr.data.newSound(frames, format, channels, sampleRate, contents) end --- ----A Blob is an object that holds binary data. It can be passed to most functions that take filename arguments, like `lovr.graphics.newModel` or `lovr.audio.newSource`. Blobs aren't usually necessary for simple projects, but they can be really helpful if: +---A Blob is an object that holds binary data. +--- +---It can be passed to most functions that take filename arguments, like `lovr.graphics.newModel` or `lovr.audio.newSource`. +--- +---Blobs aren't usually necessary for simple projects, but they can be really helpful if: --- ---- You need to work with low level binary data, potentially using the LuaJIT FFI for increased --- performance. @@ -76,13 +124,19 @@ function lovr.data.newSound(frames, format, channels, sampleRate, contents) end local Blob = {} --- ----Returns the filename the Blob was loaded from, or the custom name given to it when it was created. This label is also used in error messages. +---Returns the filename the Blob was loaded from, or the custom name given to it when it was created. +--- +---This label is also used in error messages. --- ---@return string name # The name of the Blob. function Blob:getName() end --- ----Returns a raw pointer to the Blob's data. This can be used to interface with other C libraries using the LuaJIT FFI. Use this only if you know what you're doing! +---Returns a raw pointer to the Blob's data. +--- +---This can be used to interface with other C libraries using the LuaJIT FFI. +--- +---Use this only if you know what you're doing! --- ---@return userdata pointer # A pointer to the data. function Blob:getPointer() end @@ -100,7 +154,13 @@ function Blob:getSize() end function Blob:getString() end --- ----An Image stores raw 2D pixel info for `Texture`s. It has a width, height, and format. The Image can be initialized with the contents of an image file or it can be created with uninitialized contents. The supported image formats are `png`, `jpg`, `hdr`, `dds`, `ktx`, and `astc`. +---An Image stores raw 2D pixel info for `Texture`s. +--- +---It has a width, height, and format. +--- +---The Image can be initialized with the contents of an image file or it can be created with uninitialized contents. +--- +---The supported image formats are `png`, `jpg`, `hdr`, `dds`, `ktx`, and `astc`. --- ---Usually you can just use Textures, but Image can be useful if you want to manipulate individual pixels, load Textures in a background thread, or use the FFI to efficiently access the raw image data. --- @@ -108,7 +168,9 @@ function Blob:getString() end local Image = {} --- ----Encodes the Image to an uncompressed png. This intended mainly for debugging. +---Encodes the Image to an uncompressed png. +--- +---This intended mainly for debugging. --- ---@return lovr.Blob blob # A new Blob containing the PNG image data. function Image:encode() end @@ -141,6 +203,10 @@ function Image:getHeight() end --- ---Returns the value of a pixel of the Image. --- +--- +---### NOTE: +---The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`. +--- ---@param x number # The x coordinate of the pixel to get (0-indexed). ---@param y number # The y coordinate of the pixel to get (0-indexed). ---@return number r # The red component of the pixel, from 0.0 to 1.0. @@ -158,6 +224,14 @@ function Image:getWidth() end --- ---Copies a rectangle of pixels from one Image to this one. --- +--- +---### NOTE: +---The two Images must have the same pixel format. +--- +---Compressed images cannot be copied. +--- +---The rectangle cannot go outside the dimensions of the source or destination textures. +--- ---@param source lovr.Image # The Image to copy pixels from. ---@param x? number # The x coordinate to paste to (0-indexed). ---@param y? number # The y coordinate to paste to (0-indexed). @@ -170,6 +244,10 @@ function Image:paste(source, x, y, fromX, fromY, width, height) end --- ---Sets the value of a pixel of the Image. --- +--- +---### NOTE: +---The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`. +--- ---@param x number # The x coordinate of the pixel to set (0-indexed). ---@param y number # The y coordinate of the pixel to set (0-indexed). ---@param r number # The red component of the pixel, from 0.0 to 1.0. @@ -179,7 +257,9 @@ function Image:paste(source, x, y, fromX, fromY, width, height) end function Image:setPixel(x, y, r, g, b, a) end --- ----A ModelData is a container object that loads and holds data contained in 3D model files. This can include a variety of things like the node structure of the asset, the vertex data it contains, contains, the `Image` and `Material` properties, and any included animations. +---A ModelData is a container object that loads and holds data contained in 3D model files. +--- +---This can include a variety of things like the node structure of the asset, the vertex data it contains, contains, the `Image` and `Material` properties, and any included animations. --- ---The current supported formats are OBJ, glTF, and STL. --- @@ -197,19 +277,27 @@ local ModelData = {} local Rasterizer = {} --- ----Returns the advance metric of the font, in pixels. The advance is how many pixels the font advances horizontally after each glyph is rendered. This does not include kerning. +---Returns the advance metric of the font, in pixels. +--- +---The advance is how many pixels the font advances horizontally after each glyph is rendered. +--- +---This does not include kerning. --- ---@return number advance # The advance of the font, in pixels. function Rasterizer:getAdvance() end --- ----Returns the ascent metric of the font, in pixels. The ascent represents how far any glyph of the font ascends above the baseline. +---Returns the ascent metric of the font, in pixels. +--- +---The ascent represents how far any glyph of the font ascends above the baseline. --- ---@return number ascent # The ascent of the font, in pixels. function Rasterizer:getAscent() end --- ----Returns the descent metric of the font, in pixels. The descent represents how far any glyph of the font descends below the baseline. +---Returns the descent metric of the font, in pixels. +--- +---The descent represents how far any glyph of the font descends below the baseline. --- ---@return number descent # The descent of the font, in pixels. function Rasterizer:getDescent() end @@ -227,7 +315,9 @@ function Rasterizer:getGlyphCount() end function Rasterizer:getHeight() end --- ----Returns the line height metric of the font, in pixels. This is how far apart lines are. +---Returns the line height metric of the font, in pixels. +--- +---This is how far apart lines are. --- ---@return number height # The line height of the font, in pixels. function Rasterizer:getLineHeight() end @@ -239,31 +329,75 @@ function Rasterizer:getLineHeight() end function Rasterizer:hasGlyphs() end --- ----A Sound stores the data for a sound. The supported sound formats are OGG, WAV, and MP3. Sounds cannot be played directly. Instead, there are `Source` objects in `lovr.audio` that are used for audio playback. All Source objects are backed by one of these Sounds, and multiple Sources can share a single Sound to reduce memory usage. +---A Sound stores the data for a sound. +--- +---The supported sound formats are OGG, WAV, and MP3. +--- +---Sounds cannot be played directly. +--- +---Instead, there are `Source` objects in `lovr.audio` that are used for audio playback. +--- +---All Source objects are backed by one of these Sounds, and multiple Sources can share a single Sound to reduce memory usage. --- ---Metadata ------ --- ----Sounds hold a fixed number of frames. Each frame contains one audio sample for each channel. The `SampleFormat` of the Sound is the data type used for each sample (floating point, integer, etc.). The Sound has a `ChannelLayout`, representing the number of audio channels and how they map to speakers (mono, stereo, etc.). The sample rate of the Sound indicates how many frames should be played per second. The duration of the sound (in seconds) is the number of frames divided by the sample rate. +---Sounds hold a fixed number of frames. +--- +---Each frame contains one audio sample for each channel. The `SampleFormat` of the Sound is the data type used for each sample (floating point, integer, etc.). +--- +---The Sound has a `ChannelLayout`, representing the number of audio channels and how they map to speakers (mono, stereo, etc.). +--- +---The sample rate of the Sound indicates how many frames should be played per second. +--- +---The duration of the sound (in seconds) is the number of frames divided by the sample rate. --- ---Compression ------ --- ----Sounds can be compressed. Compressed sounds are stored compressed in memory and are decoded as they are played. This uses a lot less memory but increases CPU usage during playback. OGG and MP3 are compressed audio formats. When creating a sound from a compressed format, there is an option to immediately decode it, storing it uncompressed in memory. It can be a good idea to decode short sound effects, since they won't use very much memory even when uncompressed and it will improve CPU usage. Compressed sounds can not be written to using `Sound:setFrames`. +---Sounds can be compressed. +--- +---Compressed sounds are stored compressed in memory and are decoded as they are played. +--- +---This uses a lot less memory but increases CPU usage during playback. +--- +---OGG and MP3 are compressed audio formats. +--- +---When creating a sound from a compressed format, there is an option to immediately decode it, storing it uncompressed in memory. +--- +---It can be a good idea to decode short sound effects, since they won't use very much memory even when uncompressed and it will improve CPU usage. +--- +---Compressed sounds can not be written to using `Sound:setFrames`. --- ---Streams ------ --- ----Sounds can be created as a stream by passing `'stream'` as their contents when creating them. Audio frames can be written to the end of the stream, and read from the beginning. This works well for situations where data is being generated in real time or streamed in from some other data source. +---Sounds can be created as a stream by passing `'stream'` as their contents when creating them. Audio frames can be written to the end of the stream, and read from the beginning. +--- +---This works well for situations where data is being generated in real time or streamed in from some other data source. --- ----Sources can be backed by a stream and they'll just play whatever audio is pushed to the stream. The audio module also lets you use a stream as a "sink" for an audio device. For playback devices, this works like loopback, so the mixed audio from all playing Sources will get written to the stream. For capture devices, all the microphone input will get written to the stream. Conversion between sample formats, channel layouts, and sample rates will happen automatically. +---Sources can be backed by a stream and they'll just play whatever audio is pushed to the stream. The audio module also lets you use a stream as a "sink" for an audio device. --- ----Keep in mind that streams can still only hold a fixed number of frames. If too much data is written before it is read, older frames will start to get overwritten. Similary, it's possible to read too much data without writing fast enough. +---For playback devices, this works like loopback, so the mixed audio from all playing Sources will get written to the stream. +--- +---For capture devices, all the microphone input will get written to the stream. Conversion between sample formats, channel layouts, and sample rates will happen automatically. +--- +---Keep in mind that streams can still only hold a fixed number of frames. +--- +---If too much data is written before it is read, older frames will start to get overwritten. +--- +---Similary, it's possible to read too much data without writing fast enough. --- ---Ambisonics ------ --- ----Ambisonic sounds can be imported from WAVs, but can not yet be played. Sounds with a `ChannelLayout` of `ambisonic` are stored as first-order full-sphere ambisonics using the AmbiX format (ACN channel ordering and SN3D channel normalization). The AMB format is supported for import and will automatically get converted to AmbiX. See `lovr.data.newSound` for more info. +---Ambisonic sounds can be imported from WAVs, but can not yet be played. +--- +---Sounds with a `ChannelLayout` of `ambisonic` are stored as first-order full-sphere ambisonics using the AmbiX format (ACN channel ordering and SN3D channel normalization). +--- +---The AMB format is supported for import and will automatically get converted to AmbiX. +--- +---See `lovr.data.newSound` for more info. --- ---@class lovr.Sound local Sound = {} @@ -271,11 +405,19 @@ local Sound = {} --- ---Returns a Blob containing the raw bytes of the Sound. --- +--- +---### NOTE: +---Samples for each channel are stored interleaved. +--- +---The data type of each sample is given by `Sound:getFormat`. +--- ---@return lovr.Blob blob # The Blob instance containing the bytes for the `Sound`. function Sound:getBlob() end --- ----Returns the number of channels in the Sound. Mono sounds have 1 channel, stereo sounds have 2 channels, and ambisonic sounds have 4 channels. +---Returns the number of channels in the Sound. +--- +---Mono sounds have 1 channel, stereo sounds have 2 channels, and ambisonic sounds have 4 channels. --- ---@return number channels # The number of channels in the sound. function Sound:getChannelCount() end @@ -289,6 +431,10 @@ function Sound:getChannelLayout() end --- ---Returns the duration of the Sound, in seconds. --- +--- +---### NOTE: +---This can be computed as `(frameCount / sampleRate)`. +--- ---@return number duration # The duration of the Sound, in seconds. function Sound:getDuration() end @@ -299,7 +445,13 @@ function Sound:getDuration() end function Sound:getFormat() end --- ----Returns the number of frames in the Sound. A frame stores one sample for each channel. +---Returns the number of frames in the Sound. +--- +---A frame stores one sample for each channel. +--- +--- +---### NOTE: +---For streams, this returns the number of frames in the stream's buffer. --- ---@return number frames # The number of frames in the Sound. function Sound:getFrameCount() end @@ -323,17 +475,31 @@ function Sound:getFrames(count, srcOffset) end --- ---Returns the total number of samples in the Sound. --- +--- +---### NOTE: +---For streams, this returns the number of samples in the stream's buffer. +--- ---@return number samples # The total number of samples in the Sound. function Sound:getSampleCount() end --- ----Returns the sample rate of the Sound, in Hz. This is the number of frames that are played every second. It's usually a high number like 48000. +---Returns the sample rate of the Sound, in Hz. +--- +---This is the number of frames that are played every second. +--- +---It's usually a high number like 48000. --- ---@return number frequency # The number of frames per second in the Sound. function Sound:getSampleRate() end --- ----Returns whether the Sound is compressed. Compressed sounds are loaded from compressed audio formats like MP3 and OGG. They use a lot less memory but require some extra CPU work during playback. Compressed sounds can not be modified using `Sound:setFrames`. +---Returns whether the Sound is compressed. +--- +---Compressed sounds are loaded from compressed audio formats like MP3 and OGG. +--- +---They use a lot less memory but require some extra CPU work during playback. +--- +---Compressed sounds can not be modified using `Sound:setFrames`. --- ---@return boolean compressed # Whether the Sound is compressed. function Sound:isCompressed() end @@ -365,11 +531,17 @@ function Sound:setFrames(t, count, dstOffset, srcOffset) end --- ---| '"mono"' --- ----2 channels. The first channel is for the left speaker and the second is for the right. +---2 channels. +--- +---The first channel is for the left speaker and the second is for the right. --- ---| '"stereo"' --- ----4 channels. Ambisonic channels don't map directly to speakers but instead represent directions in 3D space, sort of like the images of a skybox. Currently, ambisonic sounds can only be loaded, not played. +---4 channels. +--- +---Ambisonic channels don't map directly to speakers but instead represent directions in 3D space, sort of like the images of a skybox. +--- +---Currently, ambisonic sounds can only be loaded, not played. --- ---| '"ambisonic"' diff --git a/meta/3rd/lovr/library/lovr.event.lua b/meta/3rd/lovr/library/lovr.event.lua index 5beeb5a1..f2e9509d 100644 --- a/meta/3rd/lovr/library/lovr.event.lua +++ b/meta/3rd/lovr/library/lovr.event.lua @@ -5,6 +5,12 @@ --- ---Due to its low-level nature, it's rare to use `lovr.event` in simple projects. --- +--- +---### NOTE: +---You can define your own custom events by adding a function to the `lovr.handlers` table with a key of the name of the event you want to add. +--- +---Then, push the event using `lovr.event.push`. +--- ---@class lovr.event lovr.event = {} @@ -14,24 +20,52 @@ lovr.event = {} function lovr.event.clear() end --- ----This function returns a Lua iterator for all of the unprocessed items in the event queue. Each event consists of a name as a string, followed by event-specific arguments. This function is called in the default implementation of `lovr.run`, so it is normally not necessary to poll for events yourself. +---This function returns a Lua iterator for all of the unprocessed items in the event queue. +--- +---Each event consists of a name as a string, followed by event-specific arguments. +--- +---This function is called in the default implementation of `lovr.run`, so it is normally not necessary to poll for events yourself. --- ---@return function iterator # The iterator function, usable in a for loop. function lovr.event.poll() end --- ----Fills the event queue with unprocessed events from the operating system. This function should be called often, otherwise the operating system will consider the application unresponsive. This function is called in the default implementation of `lovr.run`. +---Fills the event queue with unprocessed events from the operating system. +--- +---This function should be called often, otherwise the operating system will consider the application unresponsive. This function is called in the default implementation of `lovr.run`. --- function lovr.event.pump() end --- ----Pushes an event onto the event queue. It will be processed the next time `lovr.event.poll` is called. For an event to be processed properly, there needs to be a function in the `lovr.handlers` table with a key that's the same as the event name. +---Pushes an event onto the event queue. +--- +---It will be processed the next time `lovr.event.poll` is called. +--- +---For an event to be processed properly, there needs to be a function in the `lovr.handlers` table with a key that's the same as the event name. +--- +--- +---### NOTE: +---Only nil, booleans, numbers, strings, and LÖVR objects are supported types for event data. --- ---@param name string # The name of the event. function lovr.event.push(name) end --- ----Pushes an event to quit. An optional number can be passed to set the exit code for the application. An exit code of zero indicates normal termination, whereas a nonzero exit code indicates that an error occurred. +---Pushes an event to quit. +--- +---An optional number can be passed to set the exit code for the application. +--- +---An exit code of zero indicates normal termination, whereas a nonzero exit code indicates that an error occurred. +--- +--- +---### NOTE: +---This function is equivalent to calling `lovr.event.push('quit', )`. +--- +---The event won't be processed until the next time `lovr.event.poll` is called. +--- +---The `lovr.quit` callback will be called when the event is processed, which can be used to do any cleanup work. +--- +---The callback can also return `false` to abort the quitting process. --- ---@param code? number # The exit code of the program. function lovr.event.quit(code) end @@ -39,10 +73,18 @@ function lovr.event.quit(code) end --- ---Pushes an event to restart the framework. --- +--- +---### NOTE: +---The event won't be processed until the next time `lovr.event.poll` is called. +--- +---The `lovr.restart` callback can be used to persist a value between restarts. +--- function lovr.event.restart() end --- ----Keys that can be pressed on a keyboard. Notably, numpad keys are missing right now. +---Keys that can be pressed on a keyboard. +--- +---Notably, numpad keys are missing right now. --- ---@alias lovr.KeyCode --- diff --git a/meta/3rd/lovr/library/lovr.filesystem.lua b/meta/3rd/lovr/library/lovr.filesystem.lua index 37fe8e0e..4f8214db 100644 --- a/meta/3rd/lovr/library/lovr.filesystem.lua +++ b/meta/3rd/lovr/library/lovr.filesystem.lua @@ -3,12 +3,40 @@ --- ---The `lovr.filesystem` module provides access to the filesystem. --- +--- +---### NOTE: +---LÖVR programs can only write to a single directory, called the save directory. +--- +---The location of the save directory is platform-specific: +--- +--- +--- +--- +--- +--- +--- +--- +--- +---
WindowsC:\Users\<user>\AppData\Roaming\LOVR\<identity>
macOS/Users/<user>/Library/Application Support/LOVR/<identity>
+--- +---`` should be a unique identifier for your app. +--- +---It can be set either in `lovr.conf` or by using `lovr.filesystem.setIdentity`. +--- +---All filenames are relative to either the save directory or the directory containing the project source. +--- +---Files in the save directory take precedence over files in the project. +--- ---@class lovr.filesystem lovr.filesystem = {} --- ---Appends content to the end of a file. --- +--- +---### NOTE: +---If the file does not exist, it is created. +--- ---@overload fun(filename: string, blob: lovr.Blob):number ---@param filename string # The file to append to. ---@param content string # A string to write to the end of the file. @@ -16,14 +44,18 @@ lovr.filesystem = {} function lovr.filesystem.append(filename, content) end --- ----Creates a directory in the save directory. Any parent directories that don't exist will also be created. +---Creates a directory in the save directory. +--- +---Any parent directories that don't exist will also be created. --- ---@param path string # The directory to create, recursively. ---@return boolean success # Whether the directory was created. function lovr.filesystem.createDirectory(path) end --- ----Returns the application data directory. This will be something like: +---Returns the application data directory. +--- +---This will be something like: --- ---- `C:\Users\user\AppData\Roaming` on Windows. ---- `/home/user/.config` on Linux. @@ -35,6 +67,10 @@ function lovr.filesystem.getAppdataDirectory() end --- ---Returns a sorted table containing all files and folders in a single directory. --- +--- +---### NOTE: +---This function calls `table.sort` to sort the results, so if `table.sort` is not available in the global scope the results are not guaranteed to be sorted. +--- ---@param path string # The directory. ---@return lovr.items table # A table with a string for each file and subfolder in the directory. function lovr.filesystem.getDirectoryItems(path) end @@ -46,7 +82,15 @@ function lovr.filesystem.getDirectoryItems(path) end function lovr.filesystem.getExecutablePath() end --- ----Returns the identity of the game, which is used as the name of the save directory. The default is `default`. It can be changed using `t.identity` in `lovr.conf`. +---Returns the identity of the game, which is used as the name of the save directory. +--- +---The default is `default`. +--- +---It can be changed using `t.identity` in `lovr.conf`. +--- +--- +---### NOTE: +---On Android, this is always the package id (like `org.lovr.app`). --- ---@return string identity # The name of the save directory, or `nil` if it isn't set. function lovr.filesystem.getIdentity() end @@ -59,14 +103,26 @@ function lovr.filesystem.getIdentity() end function lovr.filesystem.getLastModified(path) end --- ----Get the absolute path of the mounted archive containing a path in the virtual filesystem. This can be used to determine if a file is in the game's source directory or the save directory. +---Get the absolute path of the mounted archive containing a path in the virtual filesystem. +--- +---This can be used to determine if a file is in the game's source directory or the save directory. --- ---@param path string # The path to check. ---@return string realpath # The absolute path of the mounted archive containing `path`. function lovr.filesystem.getRealDirectory(path) end --- ----Returns the require path. The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d. Any question marks in the pattern will be replaced with the module that is being required. It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the virtual filesystem. +---Returns the require path. +--- +---The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d. +--- +---Any question marks in the pattern will be replaced with the module that is being required. +--- +---It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the virtual filesystem. +--- +--- +---### NOTE: +---The default reqiure path is '?.lua;?/init.lua'. --- ---@return string path # The semicolon separated list of search patterns. function lovr.filesystem.getRequirePath() end @@ -74,12 +130,24 @@ function lovr.filesystem.getRequirePath() end --- ---Returns the absolute path to the save directory. --- +--- +---### NOTE: +---The save directory takes the following form: +--- +---``` /LOVR/ ``` +--- +---Where `` is `lovr.filesystem.getAppdataDirectory` and `` is `lovr.filesystem.getIdentity` and can be customized using `lovr.conf`. +--- ---@return string path # The absolute path to the save directory. function lovr.filesystem.getSaveDirectory() end --- ---Returns the size of a file, in bytes. --- +--- +---### NOTE: +---If the file does not exist, an error is thrown. +--- ---@param file string # The file. ---@return number size # The size of the file, in bytes. function lovr.filesystem.getSize(file) end @@ -97,7 +165,9 @@ function lovr.filesystem.getSource() end function lovr.filesystem.getUserDirectory() end --- ----Returns the absolute path of the working directory. Usually this is where the executable was started from. +---Returns the absolute path of the working directory. +--- +---Usually this is where the executable was started from. --- ---@return string path # The current working directory, or `nil` if it's unknown. function lovr.filesystem.getWorkingDirectory() end @@ -125,12 +195,26 @@ function lovr.filesystem.isFused() end --- ---Load a file containing Lua code, returning a Lua chunk that can be run. --- +--- +---### NOTE: +---An error is thrown if the file contains syntax errors. +--- ---@param filename string # The file to load. ---@return function chunk # The runnable chunk. function lovr.filesystem.load(filename) end --- ----Mounts a directory or `.zip` archive, adding it to the virtual filesystem. This allows you to read files from it. +---Mounts a directory or `.zip` archive, adding it to the virtual filesystem. +--- +---This allows you to read files from it. +--- +--- +---### NOTE: +---The `append` option lets you control the priority of the archive's files in the event of naming collisions. +--- +---This function is not thread safe. +--- +---Mounting or unmounting an archive while other threads call lovr.filesystem functions is not supported. --- ---@param path string # The path to mount. ---@param mountpoint? string # The path in the virtual filesystem to mount to. @@ -149,6 +233,10 @@ function lovr.filesystem.newBlob(filename) end --- ---Read the contents of a file. --- +--- +---### NOTE: +---If the file does not exist or cannot be read, nil is returned. +--- ---@param filename string # The name of the file to read. ---@param bytes? number # The number of bytes to read (if -1, all bytes will be read). ---@return string contents # The contents of the file. @@ -158,6 +246,12 @@ function lovr.filesystem.read(filename, bytes) end --- ---Remove a file or directory in the save directory. --- +--- +---### NOTE: +---A directory can only be removed if it is empty. +--- +---To recursively remove a folder, use this function with `lovr.filesystem.getDirectoryItems`. +--- ---@param path string # The file or directory to remove. ---@return boolean success # Whether the path was removed. function lovr.filesystem.remove(path) end @@ -169,13 +263,25 @@ function lovr.filesystem.remove(path) end function lovr.filesystem.setIdentity(identity) end --- ----Sets the require path. The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d. Any question marks in the pattern will be replaced with the module that is being required. It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the save directory and the project directory. +---Sets the require path. +--- +---The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d. +--- +---Any question marks in the pattern will be replaced with the module that is being required. +--- +---It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the save directory and the project directory. +--- +--- +---### NOTE: +---The default reqiure path is '?.lua;?/init.lua'. --- ---@param path? string # An optional semicolon separated list of search patterns. function lovr.filesystem.setRequirePath(path) end --- ----Sets the location of the project's source. This can only be done once, and is usually done internally. +---Sets the location of the project's source. +--- +---This can only be done once, and is usually done internally. --- ---@param identity string # The path containing the project's source. function lovr.filesystem.setSource(identity) end @@ -183,6 +289,12 @@ function lovr.filesystem.setSource(identity) end --- ---Unmounts a directory or archive previously mounted with `lovr.filesystem.mount`. --- +--- +---### NOTE: +---This function is not thread safe. +--- +---Mounting or unmounting an archive while other threads call lovr.filesystem functions is not supported. +--- ---@param path string # The path to unmount. ---@return boolean success # Whether the archive was unmounted. function lovr.filesystem.unmount(path) end @@ -190,6 +302,12 @@ function lovr.filesystem.unmount(path) end --- ---Write to a file. --- +--- +---### NOTE: +---If the file does not exist, it is created. +--- +---If the file already has data in it, it will be replaced with the new content. +--- ---@overload fun(filename: string, blob: lovr.Blob):number ---@param filename string # The file to write to. ---@param content string # A string to write to the file. diff --git a/meta/3rd/lovr/library/lovr.graphics.lua b/meta/3rd/lovr/library/lovr.graphics.lua index 788126f7..f0ccb310 100644 --- a/meta/3rd/lovr/library/lovr.graphics.lua +++ b/meta/3rd/lovr/library/lovr.graphics.lua @@ -1,7 +1,9 @@ ---@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 `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. --- ---@class lovr.graphics lovr.graphics = {} @@ -9,6 +11,10 @@ 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) @@ -31,7 +37,9 @@ lovr.graphics = {} 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. +---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. --- ---@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) @@ -52,6 +60,10 @@ function lovr.graphics.box(mode, x, y, z, width, height, depth, angle, ax, ay, a --- ---Draws a 2D circle. --- +--- +---### 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, segments: number) ---@overload fun(mode: lovr.DrawStyle, transform: lovr.mat4, segments: number) ---@overload fun(material: lovr.Material, transform: lovr.mat4, segments: number) @@ -68,7 +80,15 @@ function lovr.graphics.box(mode, x, y, z, width, height, depth, angle, ax, ay, a function lovr.graphics.circle(mode, x, y, z, radius, angle, ax, ay, az, segments) 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. +---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. +--- +--- +---### 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. +--- +---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. --- ---@overload fun(r: number, g: number, b: number, a: number, z: number, s: number) ---@overload fun(hex: number) @@ -78,10 +98,18 @@ function lovr.graphics.circle(mode, x, y, z, radius, angle, ax, ay, az, segments function lovr.graphics.clear(color, depth, stencil) end --- ----This function runs a compute shader on the GPU. 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 function runs a compute shader on the GPU. +--- +---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. --- ---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. --- +--- +---### NOTE: +---Only compute shaders created with `lovr.graphics.newComputeShader` can be used here. +--- +---There are GPU-specific limits on the `x`, `y`, and `z` values which can be queried in the `compute` entry of `lovr.graphics.getLimits`. +--- ---@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. @@ -91,6 +119,16 @@ function lovr.graphics.compute(shader, x, y, z) end --- ---Create the desktop window, usually used to mirror the headset display. --- +--- +---### 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. +--- ---@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 @@ -114,6 +152,10 @@ function lovr.graphics.cube(mode, x, y, z, size, angle, ax, ay, az) end --- ---Draws a cylinder. --- +--- +---### NOTE: +---Currently, cylinders don't have UVs. +--- ---@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. @@ -130,7 +172,9 @@ function lovr.graphics.cube(mode, x, y, z, size, angle, ax, ay, az) end function lovr.graphics.cylinder(x, y, z, length, angle, ax, ay, az, r1, r2, capped, segments) end --- ----Discards pixel information in the active Canvas or display. This is mostly used as an optimization hint for the GPU, and is usually most helpful on mobile devices. +---Discards pixel information in the active Canvas or display. +--- +---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. @@ -140,6 +184,12 @@ function lovr.graphics.discard(color, depth, stencil) end --- ---Draws a fullscreen textured quad. --- +--- +---### NOTE: +---This function ignores stereo rendering, so it will stretch the input across the entire Canvas if it's stereo. +--- +---Special shaders are currently required for correct stereo fills. +--- ---@overload fun() ---@param texture lovr.Texture # The texture to use. ---@param u? number # The x component of the uv offset. @@ -149,18 +199,37 @@ function lovr.graphics.discard(color, depth, stencil) end function lovr.graphics.fill(texture, u, v, w, h) 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. +---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. --- function lovr.graphics.flush() 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 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. +--- +--- +---### 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. +---Returns the current background color. +--- +---Color components are from 0.0 to 1.0. +--- +--- +---### NOTE: +---The default background color is `(0.0, 0.0, 0.0, 1.0)`. --- ---@return number r # The red component of the background color. ---@return number g # The green component of the background color. @@ -169,22 +238,40 @@ function lovr.graphics.getAlphaSampling() end function lovr.graphics.getBackgroundColor() 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. +---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. --- +--- +---### 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 --- ----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. +---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. --- ---@return lovr.Canvas canvas # The active Canvas, or `nil` if no canvas is set. function lovr.graphics.getCanvas() end --- ----Returns the current global color factor. Color components are from 0.0 to 1.0. Every pixel drawn will be multiplied (i.e. tinted) by this color. +---Returns the current global color factor. +--- +---Color components are from 0.0 to 1.0. +--- +---Every pixel drawn will be multiplied (i.e. tinted) by this color. +--- +--- +---### NOTE: +---The default color is `(1.0, 1.0, 1.0, 1.0)`. --- ---@return number r # The red component of the color. ---@return number g # The green component of the color. @@ -193,12 +280,26 @@ function lovr.graphics.getCanvas() end function lovr.graphics.getColor() 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. +---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. +--- +--- +---### 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 --- ----Returns the default filter mode for new Textures. This controls how textures are sampled when they are minified, magnified, or stretched. +---Returns the default filter mode for new Textures. +--- +---This controls how textures are sampled when they are minified, magnified, or stretched. +--- +--- +---### NOTE: +---The default filter is `trilinear`. --- ---@return lovr.FilterMode mode # The filter mode. ---@return number anisotropy # The level of anisotropy. @@ -207,6 +308,28 @@ function lovr.graphics.getDefaultFilter() end --- ---Returns the current depth test settings. --- +--- +---### 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. +--- +---Smaller z values are closer to the camera. +--- +---The default compare mode is `lequal`, which usually gives good results for normal 3D rendering. +--- ---@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 @@ -245,11 +368,23 @@ function lovr.graphics.getLimits() end --- ---Returns the current line width. --- +--- +---### NOTE: +---The default line width is `1`. +--- ---@return number width # The current line width, in pixels. function lovr.graphics.getLineWidth() 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. +---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. +--- +--- +---### 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 @@ -257,12 +392,24 @@ function lovr.graphics.getPixelDensity() end --- ---Returns the current point size. --- +--- +---### 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. --- +--- +---### 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. @@ -284,7 +431,19 @@ function lovr.graphics.getShader() end function lovr.graphics.getStats() 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. +---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. +--- +--- +---### 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. @@ -311,7 +470,17 @@ function lovr.graphics.getViewPose(view) end function lovr.graphics.getWidth() 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. +---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. +--- +--- +---### 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 @@ -319,11 +488,23 @@ function lovr.graphics.getWinding() end --- ---Returns whether the desktop window is currently created. --- +--- +---### NOTE: +---Most of the `lovr.graphics` functionality will only work if a window is created. +--- ---@return boolean present # Whether a window is created. function lovr.graphics.hasWindow() end --- ----Returns whether or not culling is active. 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 whether or not culling is active. +--- +---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. +--- +--- +---### NOTE: +---Culling is disabled by default. --- ---@return boolean isEnabled # Whether or not culling is enabled. function lovr.graphics.isCullingEnabled() end @@ -331,11 +512,19 @@ function lovr.graphics.isCullingEnabled() end --- ---Returns a boolean indicating whether or not wireframe rendering is enabled. --- +--- +---### 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 --- ----Draws lines between points. Each point will be connected to the previous point in the list. +---Draws lines between points. +--- +---Each point will be connected to the previous point in the list. --- ---@overload fun(points: table) ---@param x1 number # The x coordinate of the first point. @@ -347,10 +536,18 @@ function lovr.graphics.isWireframe() end function lovr.graphics.line(x1, y1, z1, x2, y2, z2) end --- ----Creates a new Canvas. You can specify Textures to attach to it, or just specify a width and height and attach textures later using `Canvas:setTexture`. +---Creates a new Canvas. +--- +---You can specify Textures to attach to it, or just specify a width and height and attach textures later using `Canvas:setTexture`. --- ---Once created, you can render to the Canvas using `Canvas:renderTo`, or `lovr.graphics.setCanvas`. --- +--- +---### NOTE: +---Textures created by this function will have `clamp` as their `WrapMode`. +--- +---Stereo Canvases will either have their width doubled or use array textures for their attachments, depending on their implementation. +--- ---@overload fun(..., flags: table):lovr.Canvas ---@overload fun(attachments: table, flags: table):lovr.Canvas ---@param width number # The width of the canvas, in pixels. @@ -362,16 +559,32 @@ function lovr.graphics.newCanvas(width, height, flags) end --- ---Creates a new compute Shader, used for running generic compute operations on the GPU. --- +--- +---### 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. +--- +---The GLSL version used for compute shaders is GLSL 430. +--- +---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 --- ----Creates a new Font. It can be used to render text with `lovr.graphics.print`. +---Creates a new Font. +--- +---It can be used to render text with `lovr.graphics.print`. --- ---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. @@ -382,7 +595,18 @@ function lovr.graphics.newComputeShader(source, options) end function lovr.graphics.newFont(filename, size, padding, spread) 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. +---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. +--- +--- +---### 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 @@ -392,10 +616,28 @@ function lovr.graphics.newFont(filename, size, padding, spread) end function lovr.graphics.newMaterial() 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. The draw mode and usage hint can also optionally be specified. +---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. +--- +---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.' +--- +---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 @@ -409,7 +651,23 @@ function lovr.graphics.newMaterial() end function lovr.graphics.newMesh(size, mode, usage, readable) end --- ----Creates a new Model from a file. The supported 3D file formats are OBJ, glTF, and STL. +---Creates a new Model from a file. +--- +---The supported 3D file formats are OBJ, glTF, and STL. +--- +--- +---### NOTE: +---Diffuse and emissive textures will be loaded in the sRGB encoding, all other textures will be loaded as linear. +--- +---Currently, the following features are not supported by the model importer: +--- +---- 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. --- ---@overload fun(modelData: lovr.ModelData):lovr.Model ---@param filename string # The filename of the model to load. @@ -419,6 +677,87 @@ function lovr.graphics.newModel(filename) end --- ---Creates a new Shader. --- +--- +---### 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_`. +--- +---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. +--- +---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. +--- +---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`. +--- +---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. +--- +---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. +--- +---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. +--- +---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. +--- +---See the +--- `Standard Shader` guide for more information. +--- - `occlusion` is a boolean flag that uses the ambient occlusion texture in the model. +--- +---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. +--- +---Tonemapping is an important +--- process that maps the high definition physical color values down to a 0 - 1 range for +--- display. +--- +---There are lots of different tonemapping algorithms that give different artistic +--- effects. +--- +---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. +--- +---Currently, up to 32 shader flags are supported. +--- +---The `stereo` option is only necessary for Android. +--- +---Currently on Android, only stereo shaders can be used with stereo Canvases, and mono Shaders can only be used with mono Canvases. +--- ---@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. @@ -429,6 +768,14 @@ function lovr.graphics.newShader(vertex, fragment, options) 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. +--- ---@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. @@ -438,6 +785,12 @@ function lovr.graphics.newShaderBlock(type, uniforms, flags) end --- ---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. +--- ---@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 @@ -450,11 +803,21 @@ function lovr.graphics.newTexture(filename, flags) end --- ---Resets the transformation to the origin. --- +--- +---### NOTE: +---This is called at the beginning of every frame to reset the coordinate space. +--- function lovr.graphics.origin() end --- ---Draws a plane with a given position, size, and orientation. --- +--- +---### NOTE: +---The `u`, `v`, `w`, `h` arguments can be used to select a subregion of the diffuse texture to apply to the plane. +--- +---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. +--- ---@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. @@ -484,16 +847,40 @@ function lovr.graphics.points(x, y, z) end --- ---Pops the current transform from the stack, returning to the transformation that was applied before `lovr.graphics.push` was called. --- +--- +---### 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. +--- function lovr.graphics.pop() end --- ----Presents the results of pending drawing operations to the window. This is automatically called after `lovr.draw` by the default `lovr.run` function. +---Presents the results of pending drawing operations to the window. +--- +---This is automatically called after `lovr.draw` by the default `lovr.run` function. --- function lovr.graphics.present() end --- ---Draws text in 3D space using the active font. --- +--- +---### NOTE: +---Unicode text is supported. +--- +---Use `\n` to add line breaks. +--- +---`\t` will be rendered as four spaces. +--- +---LÖVR uses a fancy technique for font rendering called multichannel signed distance fields. +--- +---This leads to crisp text in VR, but requires a special shader to use. +--- +---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. @@ -509,7 +896,15 @@ function lovr.graphics.present() end function lovr.graphics.print(str, x, y, z, scale, angle, ax, ay, az, wrap, halign, valign) end --- ----Pushes a copy of the current transform onto the transformation stack. 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`. +---Pushes a copy of the current transform onto the transformation stack. +--- +---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 @@ -523,6 +918,10 @@ function lovr.graphics.reset() end --- ---The rotation will last until `lovr.draw` returns or the transformation is popped off the transformation stack. --- +--- +---### 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. @@ -530,23 +929,46 @@ function lovr.graphics.reset() end function lovr.graphics.rotate(angle, ax, ay, az) end --- ----Scales the coordinate system in 3 dimensions. This will cause objects to appear bigger or smaller. +---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. --- +--- +---### NOTE: +---Order matters when scaling, translating, and rotating the coordinate system. +--- ---@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 --- ----Enables or disables alpha sampling. 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. +---Enables or disables alpha sampling. +--- +---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. +--- +--- +---### 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). --- ---@param enabled boolean # Whether or not alpha sampling is enabled. function lovr.graphics.setAlphaSampling(enabled) end --- ----Sets the background color used to clear the screen. Color components are from 0.0 to 1.0. +---Sets the background color used to clear the screen. +--- +---Color components are from 0.0 to 1.0. +--- +--- +---### NOTE: +---The default background color is `(0.0, 0.0, 0.0, 1.0)`. --- ---@overload fun(hex: number, a: number) ---@overload fun(color: table) @@ -557,7 +979,13 @@ function lovr.graphics.setAlphaSampling(enabled) end function lovr.graphics.setBackgroundColor(r, g, b, a) end --- ----Sets the blend mode. The blend mode controls how each pixel's color is blended with the previous pixel's color when drawn. +---Sets the blend mode. +--- +---The blend mode controls how each pixel's color is blended with the previous pixel's color when drawn. +--- +--- +---### NOTE: +---The default blend mode is `alpha` and `alphamultiply`. --- ---@overload fun() ---@param blend lovr.BlendMode # The blend mode. @@ -565,13 +993,25 @@ function lovr.graphics.setBackgroundColor(r, g, b, a) end function lovr.graphics.setBlendMode(blend, alphaBlend) 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. +---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. --- ---@param canvas? lovr.Canvas # The new active Canvas object, or `nil` to just render to the headset. function lovr.graphics.setCanvas(canvas) 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. +---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. +--- +--- +---### NOTE: +---The default color is `(1.0, 1.0, 1.0, 1.0)`. --- ---@overload fun(hex: number, a: number) ---@overload fun(color: table) @@ -582,7 +1022,15 @@ function lovr.graphics.setCanvas(canvas) end function lovr.graphics.setColor(r, g, b, a) end --- ----Enables and disables individual color channels. When a color channel is enabled, it will be affected by drawing commands and clear commands. +---Enables and disables individual color channels. +--- +---When a color channel is enabled, it will be affected by drawing commands and clear commands. +--- +--- +---### 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. @@ -591,20 +1039,60 @@ function lovr.graphics.setColor(r, g, b, a) end function lovr.graphics.setColorMask(r, g, b, a) 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. +---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. +--- +--- +---### NOTE: +---Culling is disabled by default. --- ---@param isEnabled boolean # Whether or not culling should be enabled. function lovr.graphics.setCullingEnabled(isEnabled) end --- ----Sets the default filter mode for new Textures. This controls how textures are sampled when they are minified, magnified, or stretched. +---Sets the default filter mode for new Textures. +--- +---This controls how textures are sampled when they are minified, magnified, or stretched. +--- +--- +---### 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 --- ----Sets the current depth test. The depth test controls how overlapping objects are rendered. +---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. +--- +---Smaller z values are closer to the camera. +--- +---The default compare mode is `lequal`, which usually gives good results for normal 3D rendering. --- ---@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. @@ -619,19 +1107,49 @@ function lovr.graphics.setFont(font) end --- ---Sets the width of lines rendered using `lovr.graphics.line`. --- +--- +---### NOTE: +---The default line width is `1`. +--- +---GPU driver support for line widths is poor. +--- +---The actual width of lines may be different from what is set here. +--- +---In particular, some graphics drivers only support a line width of `1`. +--- +---Currently this function only supports integer values from 1 to 255. +--- ---@param width? number # The new line width, in pixels. function lovr.graphics.setLineWidth(width) end --- ---Sets the width of drawn points, in pixels. --- +--- +---### NOTE: +---The default point size is `1.0`. +--- ---@param size? number # The new point size. function lovr.graphics.setPointSize(size) end --- ----Sets the projection for a single view. 4 field of view angles can be used, similar to the field of view returned by `lovr.headset.getViewAngles`. Alternatively, a projection matrix can be used for other types of projections like orthographic, oblique, etc. +---Sets the projection for a single view. +--- +---4 field of view angles can be used, similar to the field of view returned by `lovr.headset.getViewAngles`. +--- +---Alternatively, a projection matrix can be used for other types of projections like orthographic, oblique, etc. +--- +---Two views are supported, one for each eye. +--- +---When rendering to the headset, both projections are changed to match the ones used by the headset. +--- +--- +---### NOTE: +---Non-stereo rendering will only use the first view. --- ----Two views are supported, one for each eye. When rendering to the headset, both projections are changed to match the ones used by the headset. +---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) ---@param view number # The index of the view to update. @@ -649,7 +1167,19 @@ function lovr.graphics.setProjection(view, left, right, up, down) end function lovr.graphics.setShader(shader) 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. 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. +---Sets the 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. +--- +--- +---### 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. @@ -657,9 +1187,23 @@ function lovr.graphics.setShader(shader) end function lovr.graphics.setStencilTest(compareMode, compareValue) 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. +---Sets the pose for a single view. --- ----Two views are supported, one for each eye. When rendering to the headset, both views are changed to match the estimated eye positions. These view poses are also available using `lovr.headset.getViewPose`. +---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. +--- +---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. @@ -673,19 +1217,41 @@ function lovr.graphics.setStencilTest(compareMode, compareValue) end function lovr.graphics.setViewPose(view, x, y, z, angle, ax, ay, az) end --- ----Sets the 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. The default is counterclockwise. +---Sets the 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. +--- +---The default is counterclockwise. +--- +--- +---### NOTE: +---Culling is initially disabled and must be enabled using `lovr.graphics.setCullingEnabled`. +--- +---The default winding direction is counterclockwise. --- ---@param winding lovr.Winding # The new winding direction. function lovr.graphics.setWinding(winding) end --- ----Enables or disables wireframe rendering. This is meant to be used as a debugging tool. +---Enables or disables wireframe rendering. +--- +---This is meant to be used as a debugging tool. +--- +--- +---### NOTE: +---Wireframe rendering is initially disabled. +--- +---Wireframe rendering is only supported on desktop systems. --- ---@param wireframe boolean # Whether or not wireframe rendering should be enabled. function lovr.graphics.setWireframe(wireframe) 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. +---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. --- ---@param texture lovr.Texture # The texture to use. function lovr.graphics.skybox(texture) end @@ -707,6 +1273,10 @@ function lovr.graphics.sphere(x, y, z, radius, angle, ax, ay, az) end --- ---Renders to the stencil buffer using a function. --- +--- +---### NOTE: +---Stencil values are between 0 and 255. +--- ---@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. @@ -717,18 +1287,46 @@ function lovr.graphics.stencil(callback, action, value, keep) end --- ---Starts a named timer on the GPU, which can be stopped using `lovr.graphics.tock`. --- +--- +---### 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. +--- +---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 --- ---Stops a named timer on the GPU, previously started with `lovr.graphics.tick`. --- +--- +---### NOTE: +---All drawing commands between tick and tock will be timed. +--- +---It is not possible to nest calls to tick and tock. +--- +---The results are delayed, and might be `nil` for the first few frames. +--- +---This function returns the most recent available timer value. +--- +---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. +--- ---@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 --- ----Apply a transform to the coordinate system, changing its translation, rotation, and scale using a single function. A `mat4` can also be used. +---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. --- @@ -746,25 +1344,45 @@ function lovr.graphics.tock(label) end function lovr.graphics.transform(x, y, z, sx, sy, sz, angle, ax, ay, az) 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. +---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. --- +--- +---### NOTE: +---Order matters when scaling, translating, and rotating the coordinate system. +--- ---@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 --- ----A Canvas is also known as a framebuffer or render-to-texture. 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. +---A Canvas is also known as a framebuffer or render-to-texture. +--- +---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. --- ---After creating a Canvas, you can attach Textures to it using `Canvas:setTexture`. --- +--- +---### 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. +--- +---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 = {} --- ----Returns the depth buffer used by the Canvas as a Texture. 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`. +---Returns the depth buffer used by the Canvas as a Texture. +--- +---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 @@ -772,6 +1390,10 @@ function Canvas:getDepthTexture() end --- ---Returns the dimensions of the Canvas, its Textures, and its depth buffer. --- +--- +---### NOTE: +---The dimensions of a Canvas can not be changed after it is created. +--- ---@return number width # The width of the Canvas, in pixels. ---@return number height # The height of the Canvas, in pixels. function Canvas:getDimensions() end @@ -779,11 +1401,21 @@ function Canvas:getDimensions() end --- ---Returns the height of the Canvas, its Textures, and its depth buffer. --- +--- +---### NOTE: +---The height of a Canvas can not be changed after it is created. +--- ---@return number height # The height of the Canvas, in pixels. function Canvas:getHeight() 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. +---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. +--- +--- +---### NOTE: +---All textures attached to the Canvas must be created with this MSAA value. --- ---@return number samples # The number of MSAA samples. function Canvas:getMSAA() end @@ -791,16 +1423,26 @@ function Canvas:getMSAA() end --- ---Returns the set of Textures currently attached to the Canvas. --- +--- +---### NOTE: +---Up to 4 Textures can be attached at once. +--- function Canvas:getTexture() end --- ---Returns the width of the Canvas, its Textures, and its depth buffer. --- +--- +---### NOTE: +---The width of a Canvas can not be changed after it is created. +--- ---@return number width # The width of the Canvas, in pixels. function Canvas:getWidth() 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. +---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 @@ -813,54 +1455,103 @@ function Canvas:isStereo() end function Canvas:newImage(index) 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`. +---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`. +--- +--- +---### 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. +--- +---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. function Canvas:renderTo(callback) 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. +---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. +--- +--- +---### 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. --- function Canvas:setTexture() end --- ----A Font is an object created from a TTF file. It can be used to render text with `lovr.graphics.print`. +---A Font is an object created from a TTF file. +--- +---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`. +---Returns the maximum distance that any glyph will extend above the Font's baseline. +--- +---Units are generally in meters, see `Font:getPixelDensity`. --- ---@return number ascent # The ascent of the Font. function Font:getAscent() end --- ----Returns the baseline of the Font. This is where the characters "rest on", relative to the y coordinate of the drawn text. Units are generally in meters, see `Font:setPixelDensity`. +---Returns the baseline of the Font. +--- +---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 --- ----Returns the maximum distance that any glyph will extend below the Font's baseline. 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. +---Returns the maximum distance that any glyph will extend below the Font's baseline. +--- +---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. --- ---@return number descent # The descent of the Font. function Font:getDescent() end --- ----Returns the height of a line of text. Units are in meters, see `Font:setPixelDensity`. +---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 --- ----Returns the current line height multiplier of the Font. The default is 1.0. +---Returns the current line height multiplier of the Font. +--- +---The default is 1.0. --- ---@return number lineHeight # The line height. function Font:getLineHeight() 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. +---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. --- ---@return number pixelDensity # The current pixel density. function Font:getPixelDensity() end @@ -874,6 +1565,11 @@ function Font:getRasterizer() end --- ---Returns the width and line count of a string when rendered using the font, taking into account an optional wrap limit. --- +--- +---### NOTE: +---To get the correct units returned, make sure the pixel density is set with +--- `Font:setPixelDensity`. +--- ---@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. @@ -881,32 +1577,52 @@ function Font:getRasterizer() end function Font:getWidth(text, wrap) end --- ----Returns whether the Font has a set of glyphs. Any combination of strings and numbers (corresponding to character codes) can be specified. This function will return true if the Font is able to render *all* of the glyphs. +---Returns whether the Font has a set of glyphs. +--- +---Any combination of strings and numbers (corresponding to character codes) can be specified. +--- +---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. --- ---@return boolean has # Whether the Font has the glyphs. function Font:hasGlyphs() end --- ----Sets the line height of the Font, which controls how far lines apart lines are vertically separated. This value is a ratio and the default is 1.0. +---Sets the line height of the Font, which controls how far lines apart lines are vertically separated. +--- +---This value is a ratio and the default is 1.0. --- ---@param lineHeight number # The new line height. function Font:setLineHeight(lineHeight) 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. +---Sets the pixel density for the Font. +--- +---Normally, this is in pixels per meter. +--- +---When rendering to a 2D texture, the units are pixels. --- ---@overload fun(self: lovr.Font) ---@param pixelDensity number # The new pixel density. function Font:setPixelDensity(pixelDensity) 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. +---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. --- ---@class lovr.Material local Material = {} --- ----Returns a color property for a Material. 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. +---Returns a color property for a Material. +--- +---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. --- ---@param colorType? lovr.MaterialColor # The type of color to get. ---@return number r # The red component of the color. @@ -916,14 +1632,20 @@ local Material = {} function Material:getColor(colorType) end --- ----Returns a numeric property of a Material. Scalar properties default to 1.0. +---Returns a numeric property of a Material. +--- +---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 --- ----Returns a texture for a Material. Several predefined `MaterialTexture`s are supported. Any texture that is `nil` will use a single white pixel as a fallback. +---Returns a texture for a Material. +--- +---Several predefined `MaterialTexture`s are supported. +--- +---Any texture that is `nil` will use a single white pixel as a fallback. --- ---@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. @@ -932,6 +1654,10 @@ function Material:getTexture(textureType) end --- ---Returns the transformation applied to texture coordinates of the Material. --- +--- +---### 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. +--- ---@return number ox # The texture coordinate x offset. ---@return number oy # The texture coordinate y offset. ---@return number sx # The texture coordinate x scale. @@ -940,7 +1666,11 @@ function Material:getTexture(textureType) end function Material:getTransform() end --- ----Sets a color property for a Material. 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. +---Sets a color property for a Material. +--- +---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. --- ---@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) @@ -953,14 +1683,20 @@ function Material:getTransform() end function Material:setColor(colorType, r, g, b, a) end --- ----Sets a numeric property of a Material. Scalar properties default to 1.0. +---Sets a numeric property of a Material. +--- +---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 --- ----Sets a texture for a Material. Several predefined `MaterialTexture`s are supported. Any texture that is `nil` will use a single white pixel as a fallback. +---Sets a texture for a Material. +--- +---Several predefined `MaterialTexture`s are supported. +--- +---Any texture that is `nil` will use a single white pixel as a fallback. --- ---@overload fun(self: lovr.Material, texture: lovr.Texture) ---@param textureType? lovr.MaterialTexture # The type of texture to set. @@ -968,7 +1704,13 @@ function Material:setScalar(scalarType, x) end function Material:setTexture(textureType, texture) 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. +---Sets the transformation applied to texture coordinates of the Material. +--- +---This lets you offset, scale, or rotate textures as they are applied to geometry. +--- +--- +---### 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. --- ---@param ox number # The texture coordinate x offset. ---@param oy number # The texture coordinate y offset. @@ -980,17 +1722,85 @@ function Material:setTransform(ox, oy, sx, sy, angle) 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. +---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. --- ----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. +---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. --- +--- +---### 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 } +--- } +--- +---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 = {} --- ----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. +---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. +--- +--- +---### 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. +--- +---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. +--- +---To prevent cycles, it is not possible to attach attributes onto a Mesh that already has attributes attached to a different Mesh. --- ---@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, divisor: number, ...) ---@overload fun(self: lovr.Mesh, mesh: lovr.Mesh, divisor: number, attributes: table) @@ -1028,7 +1838,9 @@ function Mesh:draw(x, y, z, scale, angle, ax, ay, az, instances) end 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. +---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. @@ -1041,7 +1853,11 @@ function Mesh:getDrawRange() end function Mesh:getMaterial() 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. +---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 @@ -1049,6 +1865,10 @@ function Mesh:getVertex(index) end --- ---Returns the components of a specific attribute of a single vertex in the Mesh. --- +--- +---### 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. +--- ---@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 @@ -1056,17 +1876,27 @@ function Mesh:getVertexAttribute(index, attribute) end --- ---Returns the maximum number of vertices the Mesh can hold. --- +--- +---### 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 --- ----Get the format table of the Mesh's vertices. The format table describes the set of data that each vertex contains. +---Get the format table of the Mesh's vertices. +--- +---The format table describes the set of data that each vertex contains. --- ---@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. +---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. --- ---@overload fun(self: lovr.Mesh, t: table):table ---@overload fun(self: lovr.Mesh, blob: lovr.Blob) @@ -1074,14 +1904,18 @@ function Mesh:getVertexFormat() end function Mesh:getVertexMap() end --- ----Returns whether or not a vertex attribute is enabled. Disabled attributes won't be sent to shaders. +---Returns whether or not a vertex attribute is enabled. +--- +---Disabled attributes won't be sent to shaders. --- ---@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 --- ----Sets whether a vertex attribute is enabled. Disabled attributes won't be sent to shaders. +---Sets whether a vertex attribute is enabled. +--- +---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. @@ -1094,7 +1928,9 @@ function Mesh:setAttributeEnabled(attribute, enabled) end function Mesh:setDrawMode(mode) end --- ----Set the draw range for the Mesh. The draw range is a subset of the vertices of the Mesh that will be drawn. +---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. @@ -1102,7 +1938,9 @@ function Mesh:setDrawMode(mode) end function Mesh:setDrawRange(start, count) end --- ----Applies a Material to the Mesh. This will cause it to use the Material's properties whenever it is rendered. +---Applies a Material to the Mesh. +--- +---This will cause it to use the Material's properties whenever it is rendered. --- ---@param material lovr.Material # The Material to apply. function Mesh:setMaterial(material) end @@ -1110,18 +1948,28 @@ function Mesh:setMaterial(material) end --- ---Update a single vertex in the Mesh. --- +--- +---### NOTE: +---Any unspecified components will be set to 0. +--- ---@param index number # The index of the vertex to set. function Mesh:setVertex(index) end --- ---Set the components of a specific attribute of a vertex in the Mesh. --- +--- +---### 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. +--- ---@param index number # The index of the vertex to update. ---@param attribute number # The index of the attribute to update. function Mesh:setVertexAttribute(index, attribute) end --- ----Sets the vertex map. The vertex map is a list of indices in the Mesh, allowing the reordering or reuse of vertices. +---Sets the vertex map. +--- +---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. --- @@ -1132,6 +1980,10 @@ function Mesh:setVertexMap(map) end --- ---Updates multiple vertices in the Mesh. --- +--- +---### NOTE: +---The start index plus the number of vertices in the table should not exceed the maximum size of the Mesh. +--- ---@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. @@ -1139,7 +1991,9 @@ function Mesh:setVertexMap(map) end function Mesh:setVertices(vertices, start, count) end --- ----A Model is a drawable object loaded from a 3D file format. The supported 3D file formats are OBJ, glTF, and STL. +---A Model is a drawable object loaded from a 3D file format. +--- +---The supported 3D file formats are OBJ, glTF, and STL. --- ---@class lovr.Model local Model = {} @@ -1147,7 +2001,17 @@ local Model = {} --- ---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. +---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`. +--- +---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. @@ -1241,6 +2105,12 @@ function Model:getNodeName(index) end --- ---Returns the pose of a single node in the Model in a given `CoordinateSpace`. --- +--- +---### NOTE: +---For skinned nodes to render correctly, use a Shader created with the `animated` flag set to `true`. +--- +---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. @@ -1256,7 +2126,9 @@ function Model:getNodePose(name, space) end --- ---Returns 2 tables containing mesh data for the Model. --- ----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 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. --- @@ -1265,16 +2137,34 @@ function Model:getNodePose(name, space) end function Model:getTriangles() end --- ----Returns whether the Model has any nodes associated with animated joints. This can be used to approximately determine whether an animated shader needs to be used with an arbitrary Model. +---Returns whether the Model has any nodes associated with animated joints. +--- +---This can be used to approximately determine whether an animated shader needs to be used with an arbitrary Model. +--- +--- +---### NOTE: +---A model can still be animated even if this function returns false, since node transforms can still be animated with keyframes without skinning. +--- +---These types of animations don't need to use a Shader with the `animated = true` flag, though. --- ---@return boolean skeletal # Whether the Model has any nodes that use skeletal animation. function Model:hasJoints() 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. +---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. --- +--- +---### NOTE: +---For skinned nodes to render correctly, use a Shader created with the `animated` flag set to `true`. +--- +---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. @@ -1289,7 +2179,100 @@ function Model:hasJoints() end function Model:pose(name, x, y, z, angle, ax, ay, az, alpha) 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. +---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. +--- +--- +---### 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. +--- +---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 = {} @@ -1297,7 +2280,9 @@ local Shader = {} --- ---Returns the type of the Shader, which will be "graphics" or "compute". --- ----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`. +---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`. --- ---@return lovr.ShaderType type # The type of the Shader. function Shader:getType() end @@ -1305,7 +2290,11 @@ function Shader:getType() end --- ---Returns whether a Shader has a block. --- ----A block is added to the Shader code at creation time using `ShaderBlock:getShaderCode`. 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. +---A block is added to the Shader code at creation time using `ShaderBlock:getShaderCode`. +--- +---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. --- ---@param block string # The name of the block. ---@return boolean present # Whether the shader has the specified block. @@ -1314,6 +2303,10 @@ function Shader:hasBlock(block) end --- ---Returns whether a Shader has a particular uniform variable. --- +--- +---### 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. +--- ---@param uniform string # The name of the uniform variable. ---@return boolean present # Whether the shader has the specified uniform. function Shader:hasUniform(uniform) end @@ -1321,13 +2314,106 @@ function Shader:hasUniform(uniform) end --- ---Updates a uniform variable in the Shader. --- +--- +---### NOTE: +---The shader does not need to be active to update its uniforms. +--- +---The following type combinations are supported: +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +--- +---
Uniform typeLÖVR type
floatnumber
intnumber
vec2{ x, y }
vec3{ x, y, z } or vec3
vec4{ x, y, z, w }
ivec2{ x, y }
ivec3{ x, y, z }
ivec4{ x, y, z, w }
mat2{ x, ... }
mat3{ x, ... }
mat4{ x, ... } or mat4
samplerTexture
imageTexture
+--- +---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: +--- +---- `sampler2D` +---- `sampler3D` +---- `samplerCube` +---- `sampler2DArray` +--- +---`Blob`s can be used to pass arbitrary binary data to Shader variables. +--- ---@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 --- ----Sends a ShaderBlock to a Shader. After the block is sent, you can update the data in the block without needing to resend the block. The block can be sent to multiple shaders and they will all see the same data from the block. +---Sends a ShaderBlock to a Shader. +--- +---After the block is sent, you can update the data in the block without needing to resend the block. +--- +---The block can be sent to multiple shaders and they will all see the same data from the block. +--- +--- +---### NOTE: +---The Shader does not need to be active to send it a block. +--- +---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. @@ -1335,7 +2421,11 @@ function Shader:send(uniform, value) end function Shader:sendBlock(name, block, access) end --- ----Sends a Texture to a Shader for writing. 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. +---Sends a Texture to a Shader for writing. +--- +---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. --- ---@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. @@ -1346,27 +2436,48 @@ function Shader:sendBlock(name, block, access) end function Shader:sendImage(name, texture, slice, mipmap, access) 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: +---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. +---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. +--- +--- +---### 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. --- ---@class lovr.ShaderBlock local ShaderBlock = {} --- ----Returns the byte offset of a variable in a ShaderBlock. This is useful if you want to manually send binary data to the ShaderBlock using a `Blob` in `ShaderBlock:send`. +---Returns the byte offset of a variable in a ShaderBlock. +--- +---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 --- ----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. Roughly, it will look something like this: +---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. +--- +---Roughly, it will look something like this: --- --- layout(std140) uniform