diff options
Diffstat (limited to 'meta/3rd/lovr/library/lovr.data.lua')
| -rw-r--r-- | meta/3rd/lovr/library/lovr.data.lua | 226 |
1 files changed, 199 insertions, 27 deletions
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"' |