\n \n | Playing | \n The source is currently playing. It can be stopped, paused, or rewound. | \n
\n \n | Paused | \n The source is paused. It can be stopped, played/resumed, or rewound. | \n
\n \n | Stopped | \n The source has been stopped. It can be played. | \n
",
key = "Source",
module = "lovr.audio",
constructors = {
"lovr.audio.newSource"
},
methods = {
{
name = "getBitDepth",
summary = "Get the bit depth of the Source.",
description = "Returns the number of bits per sample in the Source. This is a rough indicator of the \"resolution\" or quality of the Source. It's usually 16 or 32.",
key = "Source:getBitDepth",
module = "lovr.audio",
related = {
"SoundData:getBitDepth",
"AudioStream:getBitDepth"
},
variants = {
{
arguments = {},
returns = {
{
name = "bits",
type = "number",
description = "The number of bits per sample."
}
}
}
}
},
{
name = "getChannelCount",
summary = "Get the number of channels in the Source.",
description = "Returns the number of channels in the Source. Mono sounds have 1 channel and stereo sounds have 2 channels.",
key = "Source:getChannelCount",
module = "lovr.audio",
related = {
"SoundData:getChannelCount",
"AudioStream:getChannelCount"
},
variants = {
{
arguments = {},
returns = {
{
name = "channels",
type = "number",
description = "The number of channels."
}
}
}
}
},
{
name = "getCone",
summary = "Get the Source's volume cone.",
description = "Returns the directional volume cone of the Source. The cone is specified by three values: `innerAngle`, `outerAngle`, and `outerVolume`. If the listener is inside the `innerAngle`, the Source won't have its volume reduced. Otherwise, the volume will start to decrease, reaching a minimum volume of `outerVolume` once the listener is `outerAngle` degrees from the direction of the Source.",
key = "Source:getCone",
module = "lovr.audio",
notes = "The default `innerAngle` for a Source is `0`.\n\nThe default `outerAngle` for a Source is `2 * math.pi`.\n\nThe default `outerVolume` for a Source is `0`.\n\n`Source:setOrientation` can be used to change which way the cone points.",
variants = {
{
arguments = {},
returns = {
{
name = "innerAngle",
type = "number",
description = "The inner cone angle, in radians."
},
{
name = "outerAngle",
type = "number",
description = "The outer cone angle, in radians."
},
{
name = "outerVolume",
type = "number",
description = "The outer cone angle, in radians."
}
}
}
}
},
{
name = "getDuration",
summary = "Get the duration of the Source.",
description = "Returns the duration of the Source.",
key = "Source:getDuration",
module = "lovr.audio",
related = {
"AudioStream:getDuration",
"SoundData:getDuration"
},
variants = {
{
arguments = {
{
name = "unit",
type = "TimeUnit",
description = "The unit to return.",
default = "'seconds'"
}
},
returns = {
{
name = "duration",
type = "number",
description = "The duration of the Source."
}
}
}
}
},
{
name = "getFalloff",
summary = "Get the falloff parameters for the Source.",
description = "Returns parameters that control how the volume of the Source falls of with distance.",
key = "Source:getFalloff",
module = "lovr.audio",
related = {
"Source:getVolumeLimits",
"Source:setVolumeLimits"
},
variants = {
{
arguments = {},
returns = {
{
name = "reference",
type = "number",
description = "The distance at which the volume will start to decrease."
},
{
name = "max",
type = "number",
description = "The distance at which the Source will be its quietest."
},
{
name = "rolloff",
type = "number",
description = "How quickly the sound falls off between the reference and max distances (1.0 is the default)."
}
}
}
}
},
{
name = "getOrientation",
summary = "Get the orientation of the Source.",
description = "Returns the orientation of the Source, in angle/axis representation.",
key = "Source:getOrientation",
module = "lovr.audio",
related = {
"Source:getPosition",
"Source:getPose",
"Source:getCone",
"lovr.audio.getOrientation"
},
variants = {
{
arguments = {},
returns = {
{
name = "angle",
type = "number",
description = "The number of radians the Source is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
}
}
}
},
{
name = "getPitch",
summary = "Get the pitch of the Source.",
description = "Returns the current pitch factor of the Source. The default is 1.0.",
key = "Source:getPitch",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "pitch",
type = "number",
description = "The current pitch."
}
}
}
}
},
{
name = "getPose",
summary = "Get the pose of the Source.",
description = "Returns the position and orientation of the Source.",
key = "Source:getPose",
module = "lovr.audio",
related = {
"Source:getPosition",
"Source:getOrientation",
"Source:getCone",
"lovr.audio.getPose"
},
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x position of the Source, in meters."
},
{
name = "y",
type = "number",
description = "The y position of the Source, in meters."
},
{
name = "z",
type = "number",
description = "The z position of the Source, in meters."
},
{
name = "angle",
type = "number",
description = "The number of radians the Source is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
}
}
}
},
{
name = "getPosition",
summary = "Get the position of the Source.",
description = "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.",
key = "Source:getPosition",
module = "lovr.audio",
related = {
"Source:getOrientation",
"Source:getPose",
"Source:getCone",
"lovr.audio.getPosition"
},
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x coordinate."
},
{
name = "y",
type = "number",
description = "The y coordinate."
},
{
name = "z",
type = "number",
description = "The z coordinate."
}
}
}
}
},
{
name = "getSampleRate",
summary = "Get the sample rate of the Source.",
description = "Returns the number of samples per second in the Source. This is usually a high number like 44100.",
key = "Source:getSampleRate",
module = "lovr.audio",
related = {
"SoundData:getSampleRate",
"AudioStream:getSampleRate"
},
variants = {
{
arguments = {},
returns = {
{
name = "frequency",
type = "number",
description = "The number of samples per second in the Source."
}
}
}
}
},
{
name = "getType",
summary = "Get the SourceType of the Source.",
description = "Returns the SourceType of the Source that controls how the Source decodes audio. See `SourceType` for more info.",
key = "Source:getType",
module = "lovr.audio",
related = {
"SourceType",
"lovr.audio.newSource"
},
variants = {
{
arguments = {},
returns = {
{
name = "type",
type = "SourceType",
description = "The SourceType of the Source."
}
}
}
}
},
{
name = "getVelocity",
summary = "Get the velocity of the Source.",
description = "Returns the velocity of the Source, in meters per second. This affects the doppler effect.",
key = "Source:getVelocity",
module = "lovr.audio",
notes = "The Source does not move based on its velocity.",
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x velocity."
},
{
name = "y",
type = "number",
description = "The y velocity."
},
{
name = "z",
type = "number",
description = "The z velocity."
}
}
}
}
},
{
name = "getVolume",
summary = "Get the volume of the Source.",
description = "Returns the current volume factor for the Source. 1.0 is the default and the maximum.",
key = "Source:getVolume",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "volume",
type = "number",
description = "The volume of the Source."
}
}
}
}
},
{
name = "getVolumeLimits",
summary = "Get the volume limits of the Source.",
description = "Returns the minimum and maximum volume of the Source. These limits have priority over the parameters set by `Source:setFalloff` and `Source:setCone`, so they can be used to make sure a Source can always be heard even if it's far away.",
key = "Source:getVolumeLimits",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "min",
type = "number",
description = "The minimum volume of the Source."
},
{
name = "max",
type = "number",
description = "The maximum volume of the Source."
}
}
}
}
},
{
name = "isLooping",
summary = "Check if the Source is looping.",
description = "Returns whether or not the Source will loop when it finishes.",
key = "Source:isLooping",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "looping",
type = "boolean",
description = "Whether or not the Source is looping."
}
}
}
}
},
{
name = "isPaused",
summary = "Check if the Source is paused.",
description = "Returns whether or not the Source is paused.",
key = "Source:isPaused",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "paused",
type = "boolean",
description = "Whether the Source is paused."
}
}
}
}
},
{
name = "isPlaying",
summary = "Check if the Source is playing.",
description = "Returns whether or not the Source is playing.",
key = "Source:isPlaying",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "playing",
type = "boolean",
description = "Whether the Source is playing."
}
}
}
}
},
{
name = "isRelative",
summary = "Check if the Source is relative to the listener.",
description = "Returns whether or not the Source is relative to the listener. If a Source is relative then its position, velocity, cone, and orientation are all treated as relative to the audio listener, instead of absolute positions in space.",
key = "Source:isRelative",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "relative",
type = "boolean",
description = "Whether or not the Source is relative."
}
}
}
}
},
{
name = "isStopped",
summary = "Check if the Source is stopped.",
description = "Returns whether or not the Source is stopped.",
key = "Source:isStopped",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "stopped",
type = "boolean",
description = "Whether the Source is stopped."
}
}
}
}
},
{
name = "pause",
summary = "Pause the Source.",
description = "Pauses the source. It can be resumed with `Source:resume` or `Source:play`. If a paused source is rewound, it will remain paused.",
key = "Source:pause",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "play",
summary = "Play the Source.",
description = "Plays the Source. This doesn't do anything if the Source is already playing.",
key = "Source:play",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "resume",
summary = "Resume the Source.",
description = "Resumes the Source.",
key = "Source:resume",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "rewind",
summary = "Rewind the Source.",
description = "Rewinds the Source, starting it over at the beginning. Paused Sources will remain paused.",
key = "Source:rewind",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "seek",
summary = "Set the playback position of the Source.",
description = "Seeks the Source to the specified position.",
key = "Source:seek",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "position",
type = "number",
description = "The position to seek to."
},
{
name = "unit",
type = "TimeUnit",
description = "The units for the seek position.",
default = "'seconds'"
}
},
returns = {}
}
}
},
{
name = "setCone",
summary = "Set the Source's volume cone.",
description = "Sets the directional volume cone of the Source. The cone is specified by three values: `innerAngle`, `outerAngle`, and `outerVolume`. If the listener is inside the `innerAngle`, the Source won't have its volume changed. Otherwise, the volume will start to decrease, reaching a minimum volume of `outerVolume` once the listener is `outerAngle` degrees from the direction of the Source.",
key = "Source:setCone",
module = "lovr.audio",
notes = "The default `innerAngle` for a Source is `0`.\n\nThe default `outerAngle` for a Source is `2 * math.pi`.\n\nThe default `outerVolume` for a Source is `0`.\n\nThe direction of the cone can be changed using `Source:setOrientation`.",
variants = {
{
arguments = {
{
name = "innerAngle",
type = "number",
description = "The inner cone angle, in radians."
},
{
name = "outerAngle",
type = "number",
description = "The outer cone angle, in radians."
},
{
name = "outerVolume",
type = "number",
description = "The outer cone angle, in radians."
}
},
returns = {}
}
}
},
{
name = "setFalloff",
summary = "Set the falloff parameters for the Source.",
description = "Sets parameters that control how the volume of the Source falls of with distance.\n\nOnly mono sources support positional falloff. Using this function on a stereo Source will cause an error.",
key = "Source:setFalloff",
module = "lovr.audio",
related = {
"Source:getVolumeLimits",
"Source:setVolumeLimits"
},
variants = {
{
arguments = {
{
name = "reference",
type = "number",
description = "The distance at which the volume will start to decrease."
},
{
name = "max",
type = "number",
description = "The distance at which the Source will be its quietest."
},
{
name = "rolloff",
type = "number",
description = "How quickly the sound falls off between the reference and max distances (1.0 is the default)."
}
},
returns = {}
}
}
},
{
name = "setLooping",
summary = "Set whether or not the Source loops.",
description = "Sets whether or not the Source loops.",
key = "Source:setLooping",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "loop",
type = "boolean",
description = "Whether or not the Source will loop."
}
},
returns = {}
}
}
},
{
name = "setOrientation",
summary = "Set the orientation of the Source.",
description = "Sets the orientation of the Source in angle/axis representation.",
key = "Source:setOrientation",
module = "lovr.audio",
related = {
"Source:setPosition",
"Source:setPose",
"Source:setCone",
"lovr.audio.setOrientation"
},
variants = {
{
arguments = {
{
name = "angle",
type = "number",
description = "The number of radians the Source should be rotated around its rotation axis."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
},
returns = {}
}
}
},
{
name = "setPitch",
summary = "Set the pitch of the Source.",
description = "Sets the pitch of the Source. The default is 1.0.",
key = "Source:setPitch",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "pitch",
type = "number",
description = "The new pitch."
}
},
returns = {}
}
}
},
{
name = "setPose",
summary = "Set the pose of the Source.",
description = "Sets the position and orientation of the Source.",
key = "Source:setPose",
module = "lovr.audio",
related = {
"Source:setPosition",
"Source:setOrientation",
"lovr.audio.setPose"
},
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x position of the Source, in meters."
},
{
name = "y",
type = "number",
description = "The y position of the Source, in meters."
},
{
name = "z",
type = "number",
description = "The z position of the Source, in meters."
},
{
name = "angle",
type = "number",
description = "The number of radians the Source is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
},
returns = {}
}
}
},
{
name = "setPosition",
summary = "Set the position of the Source.",
description = "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.\n\nOnly mono sources can be positioned. Setting the position of a stereo Source will cause an error.",
key = "Source:setPosition",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x coordinate."
},
{
name = "y",
type = "number",
description = "The y coordinate."
},
{
name = "z",
type = "number",
description = "The z coordinate."
}
},
returns = {}
}
}
},
{
name = "setRelative",
summary = "Set whether or not the Source is relative.",
description = "Sets whether or not the Source is relative to the listener. If a Source is relative then its position, velocity, cone, and orientation are all treated as relative to the audio listener.",
key = "Source:setRelative",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "relative",
type = "boolean",
description = "Whether or not the Source should be relative."
}
},
returns = {}
}
}
},
{
name = "setVelocity",
summary = "Set the velocity of the Source.",
description = "Sets the velocity of the Source, in meters per second. This affects the doppler effect.",
key = "Source:setVelocity",
module = "lovr.audio",
notes = "The Source does not move based on its velocity.",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x velocity."
},
{
name = "y",
type = "number",
description = "The y velocity."
},
{
name = "z",
type = "number",
description = "The z velocity."
}
},
returns = {}
}
}
},
{
name = "setVolume",
summary = "Set the volume of the Source.",
description = "Sets the current volume factor for the Source. 1.0 is the default and the maximum.",
key = "Source:setVolume",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "volume",
type = "number",
description = "The new volume."
}
},
returns = {}
}
}
},
{
name = "setVolumeLimits",
summary = "Set the volume limits of the Source.",
description = "Sets the minimum and maximum volume of the Source. These limits have priority over the parameters set by `Source:setFalloff` and `Source:setCone`, so they can be used to make sure a Source can always be heard even if it's far away.",
key = "Source:setVolumeLimits",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "min",
type = "number",
description = "The minimum volume of the Source."
},
{
name = "max",
type = "number",
description = "The maximum volume of the Source."
}
},
returns = {}
}
}
},
{
name = "stop",
summary = "Stop the Source.",
description = "Stops the source, also rewinding it to the beginning.",
key = "Source:stop",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "tell",
summary = "Get the playback position of the Source.",
description = "Returns the current playback position of the Source.",
key = "Source:tell",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "unit",
type = "TimeUnit",
description = "The unit to return.",
default = "'seconds'"
}
},
returns = {
{
name = "position",
type = "number",
description = "The current playback position."
}
}
}
}
}
}
}
},
functions = {
{
name = "getDopplerEffect",
tag = "listener",
summary = "Get the doppler effect parameters.",
description = "Returns the parameters that control the simulated doppler effect.",
key = "lovr.audio.getDopplerEffect",
module = "lovr.audio",
notes = "The default factor is 1.0 and the default speed of sound is 343.29.",
variants = {
{
arguments = {},
returns = {
{
name = "factor",
type = "number",
description = "The doppler effect scaling factor."
},
{
name = "speedOfSound",
type = "number",
description = "The speed of sound, in meters per second."
}
}
}
}
},
{
name = "getMicrophoneNames",
tag = "microphones",
summary = "Get the names of all connected microphones.",
description = "Returns a table with the names of all microphones connected to the system.",
key = "lovr.audio.getMicrophoneNames",
module = "lovr.audio",
related = {
"lovr.audio.newMicrophone",
"Microphone"
},
variants = {
{
arguments = {},
returns = {
{
name = "names",
type = "table",
description = "The list of microphone names as strings."
}
}
},
{
arguments = {
{
name = "t",
type = "table",
description = "A table to fill with the microphone names."
}
},
returns = {
{
name = "t",
type = "table",
description = "The original table that was passed in."
}
}
}
}
},
{
name = "getOrientation",
tag = "listener",
summary = "Get the orientation of the listener.",
description = "Returns the orientation of the virtual audio listener in angle/axis representation.",
key = "lovr.audio.getOrientation",
module = "lovr.audio",
related = {
"lovr.audio.getPosition",
"lovr.audio.getPose",
"Source:getOrientation"
},
variants = {
{
arguments = {},
returns = {
{
name = "angle",
type = "number",
description = "The number of radians the listener is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
}
}
}
},
{
name = "getPose",
tag = "listener",
summary = "Get the pose of the listener.",
description = "Returns the position and orientation of the virtual audio listener.",
key = "lovr.audio.getPose",
module = "lovr.audio",
related = {
"lovr.audio.getPosition",
"lovr.audio.getOrientation",
"Source:getPose"
},
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x position of the listener, in meters."
},
{
name = "y",
type = "number",
description = "The y position of the listener, in meters."
},
{
name = "z",
type = "number",
description = "The z position of the listener, in meters."
},
{
name = "angle",
type = "number",
description = "The number of radians the listener is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
}
}
}
},
{
name = "getPosition",
tag = "listener",
summary = "Get the position of the listener.",
description = "Returns the position of the virtual audio listener, in meters.",
key = "lovr.audio.getPosition",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x position of the listener."
},
{
name = "y",
type = "number",
description = "The y position of the listener."
},
{
name = "z",
type = "number",
description = "The z position of the listener."
}
}
}
}
},
{
name = "getVelocity",
tag = "listener",
summary = "Get the velocity of the audio listener.",
description = "Returns the velocity of the audio listener, in meters per second. This affects the doppler effect.",
key = "lovr.audio.getVelocity",
module = "lovr.audio",
notes = "The audio listener does not move based on its velocity.",
variants = {
{
arguments = {},
returns = {
{
name = "x",
type = "number",
description = "The x velocity."
},
{
name = "y",
type = "number",
description = "The y velocity."
},
{
name = "z",
type = "number",
description = "The z velocity."
}
}
}
}
},
{
name = "getVolume",
tag = "listener",
summary = "Get the master volume.",
description = "Returns the master volume. All Source objects have their volume multiplied by this factor.",
key = "lovr.audio.getVolume",
module = "lovr.audio",
notes = "The default is 1.0.",
variants = {
{
arguments = {},
returns = {
{
name = "volume",
type = "number",
description = "The master volume."
}
}
}
}
},
{
name = "isSpatialized",
tag = "listener",
summary = "Check if audio is spatialized.",
description = "Returns whether or not audio is currently spatialized with HRTFs.",
key = "lovr.audio.isSpatialized",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {
{
name = "spatialized",
type = "boolean",
description = "Whether or not audio is spatialized."
}
}
}
}
},
{
name = "newMicrophone",
tag = "microphones",
summary = "Create a new Microphone.",
description = "Creates a new Microphone based on the name of an existing micrphone and a set of capture parameters. If the specified combination of prameters are not supported for audio capture, `nil` will be returned.",
key = "lovr.audio.newMicrophone",
module = "lovr.audio",
related = {
"lovr.audio.getMicrophoneNames",
"Microphone"
},
variants = {
{
arguments = {
{
name = "name",
type = "string",
description = "The name of the microphone that this Microphone will record from, or `nil` to use the default microphone.",
default = "nil"
},
{
name = "samples",
type = "number",
description = "The maximum number of samples that will be stored in the Microphone's internal buffer.",
default = "1024"
},
{
name = "sampleRate",
type = "number",
description = "The number of audio samples to record each second.",
default = "8000"
},
{
name = "bitDepth",
type = "number",
description = "The number of bits occupied by each sample. Usually 8 or 16.",
default = "16"
},
{
name = "channelCount",
type = "number",
description = "The number of channels to record (1 for mono, 2 for stereo).",
default = "1"
}
},
returns = {
{
name = "microphone",
type = "Microphone",
description = "The new Microphone, or `nil` if the capture settings are not supported."
}
}
}
}
},
{
name = "newSource",
tag = "sources",
summary = "Create a new Source.",
description = "Creates a new Source from an ogg file.",
key = "lovr.audio.newSource",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the sound to load."
},
{
name = "type",
type = "SourceType",
description = "How to stream in audio data."
}
},
returns = {
{
name = "source",
type = "Source",
description = "The new Source."
}
}
},
{
arguments = {
{
name = "blob",
type = "Blob",
description = "The Blob containing the Source data."
},
{
name = "type",
type = "SourceType",
description = "How to stream in audio data."
}
},
returns = {
{
name = "source",
type = "Source",
description = "The new Source."
}
}
},
{
arguments = {
{
name = "stream",
type = "AudioStream",
description = "The AudioStream used to stream audio data to the Source."
},
{
name = "type",
type = "SourceType",
description = "How to stream in audio data."
}
},
returns = {
{
name = "source",
type = "Source",
description = "The new Source."
}
}
},
{
arguments = {
{
name = "soundData",
type = "SoundData",
description = "The SoundData containing raw audio samples to play."
}
},
returns = {
{
name = "source",
type = "Source",
description = "The new Source."
}
}
}
}
},
{
name = "pause",
tag = "sources",
summary = "Pause all Sources.",
description = "Pause all playing audio.",
key = "lovr.audio.pause",
module = "lovr.audio",
related = {
"Source:pause",
"lovr.audio.resume",
"lovr.audio.rewind",
"lovr.audio.stop"
},
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "resume",
tag = "sources",
summary = "Resume all Sources.",
description = "Resume all Sources. Has no effect on Sources that are playing or stopped.",
key = "lovr.audio.resume",
module = "lovr.audio",
related = {
"Source:resume",
"Source:resume",
"lovr.audio.pause",
"lovr.audio.rewind",
"lovr.audio.stop"
},
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "rewind",
tag = "sources",
summary = "Rewind all Sources.",
description = "Rewind all playing audio.",
key = "lovr.audio.rewind",
module = "lovr.audio",
notes = "Sources that are paused will remain paused. Sources that are currently playing will restart from the beginning.",
related = {
"Source:rewind",
"lovr.audio.pause",
"lovr.audio.resume",
"lovr.audio.stop"
},
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "setDopplerEffect",
tag = "listener",
summary = "Set the doppler effect parameters.",
description = "Sets the parameters that control the simulated doppler effect: The effect intensity and the speed of sound.",
key = "lovr.audio.setDopplerEffect",
module = "lovr.audio",
notes = "The default factor is 1.0 and the default speed of sound is 343.29.",
variants = {
{
arguments = {
{
name = "factor",
type = "number",
description = "The doppler effect scaling factor.",
default = "1.0"
},
{
name = "speedOfSound",
type = "number",
description = "The speed of sound, in meters per second.",
default = "343.29"
}
},
returns = {}
}
}
},
{
name = "setOrientation",
tag = "listener",
summary = "Set the orientation of the listener.",
description = "Sets the orientation of the virtual audio listener in angle/axis representation.",
key = "lovr.audio.setOrientation",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "angle",
type = "number",
description = "The number of radians the listener should be rotated around its rotation axis."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
},
returns = {}
}
}
},
{
name = "setPose",
tag = "listener",
summary = "Set the pose of the listener.",
description = "Sets the position and orientation of the virtual audio listener.",
key = "lovr.audio.setPose",
module = "lovr.audio",
notes = "The default implementation of `lovr.run` calls this function with the result of `lovr.headset.getPose`, so that the listener automatically tracks the headset.",
related = {
"lovr.audio.setPosition",
"lovr.audio.setOrientation",
"Source:setPose"
},
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x position of the listener, in meters."
},
{
name = "y",
type = "number",
description = "The y position of the listener, in meters."
},
{
name = "z",
type = "number",
description = "The z position of the listener, in meters."
},
{
name = "angle",
type = "number",
description = "The number of radians the listener is rotated around its axis of rotation."
},
{
name = "ax",
type = "number",
description = "The x component of the axis of rotation."
},
{
name = "ay",
type = "number",
description = "The y component of the axis of rotation."
},
{
name = "az",
type = "number",
description = "The z component of the axis of rotation."
}
},
returns = {}
}
}
},
{
name = "setPosition",
tag = "listener",
summary = "Set the position of the listener.",
description = "Sets the position of the virtual audio listener, in meters.",
key = "lovr.audio.setPosition",
module = "lovr.audio",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x position of the listener."
},
{
name = "y",
type = "number",
description = "The y position of the listener."
},
{
name = "z",
type = "number",
description = "The z position of the listener."
}
},
returns = {}
}
}
},
{
name = "setVelocity",
tag = "listener",
summary = "Set the velocity of the audio listener.",
description = "Sets the velocity of the audio listener, in meters per second. This affects the doppler effect.",
key = "lovr.audio.setVelocity",
module = "lovr.audio",
notes = "The audio listener does not move based on its velocity.",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x velocity."
},
{
name = "y",
type = "number",
description = "The y velocity."
},
{
name = "z",
type = "number",
description = "The z velocity."
}
},
returns = {}
}
}
},
{
name = "setVolume",
tag = "listener",
summary = "Set the master volume.",
description = "Sets the master volume. The volume of all Sources will be multiplied by this factor.",
key = "lovr.audio.setVolume",
module = "lovr.audio",
notes = "The default is 1.0.",
variants = {
{
arguments = {},
returns = {
{
name = "volume",
type = "number",
description = "The master volume."
}
}
}
}
},
{
name = "stop",
tag = "sources",
summary = "Stop all Sources.",
description = "Stops all audio.",
key = "lovr.audio.stop",
module = "lovr.audio",
notes = "If you want to resume the stopped audio later, see `lovr.audio.pause`.",
related = {
"Source:stop",
"lovr.audio.pause",
"lovr.audio.resume",
"lovr.audio.rewind"
},
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "update",
tag = "sources",
summary = "Updates the audio system.",
description = "Updates all playing sources. This must be called regularly for audio playback to occur. This is called automatically by the default implementation of `lovr.run`.",
key = "lovr.audio.update",
module = "lovr.audio",
variants = {
{
arguments = {},
returns = {}
}
}
}
},
enums = {
{
name = "SourceType",
summary = "Different ways to handle audio data for Source objects.",
description = "When you create a Source, you can either decode audio data gradually over time or you can decode it all at once. Streaming it over time will use less memory but cause higher processing overhead because audio is continuously being decoded. On the other hand, decoding a sound all at once means it will take more time to load and use more memory, but after it's loaded there is virtually no processing overhead. It's recommended to use the 'static' mode for short sound effects and the 'stream' mode for longer music tracks.",
key = "SourceType",
module = "lovr.audio",
values = {
{
name = "static",
description = "Decode the entire sound file up front."
},
{
name = "stream",
description = "Decode the sound gradually over time."
}
}
},
{
name = "TimeUnit",
summary = "Time units for sound samples.",
description = "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 samples.",
key = "TimeUnit",
module = "lovr.audio",
values = {
{
name = "seconds",
description = "Seconds."
},
{
name = "samples",
description = "Samples."
}
}
}
},
sections = {
{
name = "Sources",
tag = "sources",
description = "Sources are objects that represent a single sound instance."
},
{
name = "Listener",
tag = "listener",
description = "The listener is a virtual object in 3D space that \"hears\" all the sounds that are playing. The listener can be positioned and oriented in 3D space, which controls how Sources in the world are heard. For example, sounds further away from the listener will be more quiet, and sounds to the left of the listener will be heard from the left speaker. By default, the listener will be synchronized with any connected headset so audio is positioned properly as the headset is moved around and rotated."
},
{
name = "Microphones",
tag = "microphones",
description = "Microphones can be used to receive audio input."
}
}
},
{
name = "data",
tag = "modules",
summary = "Exposes low level functions for working with data.",
description = "The `lovr.data` module provides functions for accessing underlying data representations for several LÖVR objects.",
key = "lovr.data",
objects = {
{
name = "AudioStream",
summary = "An object that gradually decodes audio data.",
description = "An AudioStream is an object that reads and decodes compressed sound data. All Source objects are powered by AudioStreams.\n\nUsually you can just use Sources without having to deal with AudioStreams, but sometimes you may need low-level access to the audio stream.",
key = "AudioStream",
module = "lovr.data",
constructors = {
"lovr.data.newAudioStream"
},
methods = {
{
name = "decode",
summary = "Decode the next chunk of audio in the AudioStream.",
description = "Returns a new SoundData containing the next chunk of audio in the AudioStream.",
key = "AudioStream:decode",
module = "lovr.data",
notes = "This function may return nil if there isn't any audio left in the stream.",
variants = {
{
arguments = {},
returns = {
{
name = "soundData",
type = "SoundData",
description = "The SoundData object containing raw audio samples."
}
}
}
}
},
{
name = "getBitDepth",
summary = "Get the bit depth of the AudioStream.",
description = "Returns the number of bits per sample in the stream's sound data. This is a rough indicator of the \"resolution\" of the sound, and is usually 16.",
key = "AudioStream:getBitDepth",
module = "lovr.data",
related = {
"SoundData:getBitDepth",
"Source:getBitDepth"
},
variants = {
{
arguments = {},
returns = {
{
name = "bits",
type = "number",
description = "The number of bits per sample."
}
}
}
}
},
{
name = "getChannelCount",
summary = "Get the number of channels in the AudioStream.",
description = "Returns the number of channels present in the stream's sound data. Mono sounds have 1 channel and stereo sounds have 2 channels.",
key = "AudioStream:getChannelCount",
module = "lovr.data",
related = {
"SoundData:getChannelCount",
"Source:getChannelCount"
},
variants = {
{
arguments = {},
returns = {
{
name = "channels",
type = "number",
description = "The number of channels."
}
}
}
}
},
{
name = "getDuration",
summary = "Get the duration of the AudioStream.",
description = "Returns the duration of the sound data in seconds.",
key = "AudioStream:getDuration",
module = "lovr.data",
related = {
"SoundData:getDuration",
"Source:getDuration"
},
variants = {
{
arguments = {},
returns = {
{
name = "duration",
type = "number",
description = "The duration of the sound."
}
}
}
}
},
{
name = "getSampleRate",
summary = "Get the sample rate of the AudioStream.",
description = "Returns the number of samples per second in the stream's sound data. This is usually a high number like 44100.",
key = "AudioStream:getSampleRate",
module = "lovr.data",
related = {
"SoundData:getSampleRate",
"Source:getSampleRate"
},
variants = {
{
arguments = {},
returns = {
{
name = "frequency",
type = "number",
description = "The number of samples per second in the AudioStream."
}
}
}
}
}
}
},
{
name = "Blob",
summary = "A chunk of binary data.",
description = "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:\n\n- You need to work with low level binary data, potentially using the LuaJIT FFI for increased\n performance.\n- You are working with data that isn't stored as a file, such as programmatically generated data\n or a string from a network request.\n- You want to load data from a file once and then use it to create many different objects.\n\nA Blob's size cannot be changed once it is created.",
key = "Blob",
module = "lovr.data",
constructors = {
"lovr.data.newBlob",
"lovr.filesystem.newBlob"
},
methods = {
{
name = "getName",
summary = "Get the label of the Blob.",
description = "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.",
key = "Blob:getName",
module = "lovr.data",
variants = {
{
arguments = {},
returns = {
{
name = "name",
type = "string",
description = "The name of the Blob."
}
}
}
}
},
{
name = "getPointer",
summary = "Get a raw pointer to the Blob's data.",
description = "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!",
key = "Blob:getPointer",
module = "lovr.data",
variants = {
{
arguments = {},
returns = {
{
name = "pointer",
type = "userdata",
description = "A pointer to the data."
}
}
}
}
},
{
name = "getSize",
summary = "Get the size of the Blob's data.",
description = "Returns the size of the Blob's contents, in bytes.",
key = "Blob:getSize",
module = "lovr.data",
variants = {
{
arguments = {},
returns = {
{
name = "bytes",
type = "number",
description = "The size of the Blob, in bytes."
}
}
}
}
},
{
name = "getString",
summary = "Get the Blob's contents as a string.",
description = "Returns a binary string containing the Blob's data.",
key = "Blob:getString",
module = "lovr.data",
variants = {
{
arguments = {},
returns = {
{
name = "data",
type = "string",
description = "The Blob's data."
}
}
}
},
examples = {
{
description = "Manually copy a file using Blobs:",
code = "blob = lovr.filesystem.newBlob('image.png')\nlovr.filesystem.write('copy.png', blob:getString())"
}
}
}
}
},
{
name = "ModelData",
summary = "An object that loads and stores data for 3D models.",
description = "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 `TextureData` and `Material` properties, and any included animations.\n\nThe current supported formats are OBJ and glTF.\n\nUsually you can just load a `Model` directly, but using a `ModelData` can be helpful if you want to load models in a thread or access more low-level information about the Model.",
key = "ModelData",
module = "lovr.data",
constructors = {
"lovr.data.newModelData"
},
methods = {}
},
{
name = "Rasterizer",
summary = "An object that rasterizes glyphs from font files.",
description = "A Rasterizer is an object that parses a TTF file, decoding and rendering glyphs from it.\n\nUsually you can just use `Font` objects.",
key = "Rasterizer",
module = "lovr.data",
constructors = {
"lovr.data.newRasterizer"
},
methods = {
{
name = "getAdvance",
summary = "Get the advance of the font.",
description = "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.",
key = "Rasterizer:getAdvance",
module = "lovr.data",
variants = {
{
arguments = {},
returns = {
{
name = "advance",
type = "number",
description = "The advance of the font, in pixels."
}
}
}
}
},
{
name = "getAscent",
summary = "Get the ascent of the font.",
description = "Returns the ascent metric of the font, in pixels. The ascent represents how far any glyph of the font ascends above the baseline.",
key = "Rasterizer:getAscent",
module = "lovr.data",
related = {
"Rasterizer:getDescent",
"Font:getAscent"
},
variants = {
{
arguments = {},
returns = {
{
name = "ascent",
type = "number",
description = "The ascent of the font, in pixels."
}
}
}
}
},
{
name = "getDescent",
summary = "Get the descent of the font.",
description = "Returns the descent metric of the font, in pixels. The descent represents how far any glyph of the font descends below the baseline.",
key = "Rasterizer:getDescent",
module = "lovr.data",
related = {
"Rasterzer:getAscent",
"Font:getDescent"
},
variants = {
{
arguments = {},
returns = {
{
name = "descent",
type = "number",
description = "The descent of the font, in pixels."
}
}
}
}
},
{
name = "getGlyphCount",
summary = "Get the number of glyphs stored in the font file.",
description = "Returns the number of glyphs stored in the font file.",
key = "Rasterizer:getGlyphCount",
module = "lovr.data",
related = {
"Rasterizer:hasGlyphs"
},
variants = {
{
arguments = {},
returns = {
{
name = "count",
type = "number",
description = "The number of glyphs stored in the font file."
}
}
}
}
},
{
name = "getHeight",
summary = "Get the height of the font.",
description = "Returns the height metric of the font, in pixels.",
key = "Rasterizer:getHeight",
module = "lovr.data",
related = {
"Font:getHeight"
},
variants = {
{
arguments = {},
returns = {
{
name = "height",
type = "number",
description = "The height of the font, in pixels."
}
}
}
}
},
{
name = "getLineHeight",
summary = "Get the line height of the font.",
description = "Returns the line height metric of the font, in pixels. This is how far apart lines are.",
key = "Rasterizer:getLineHeight",
module = "lovr.data",
related = {
"Rasterizer:getHeight",
"Font:getLineHeight",
"Font:setLineHeight"
},
variants = {
{
arguments = {},
returns = {
{
name = "height",
type = "number",
description = "The line height of the font, in pixels."
}
}
}
}
},
{
name = "hasGlyphs",
summary = "Get whether the Rasterizer can rasterize a set of glyphs.",
description = "Check if the Rasterizer can rasterize a set of glyphs.",
key = "Rasterizer:hasGlyphs",
module = "lovr.data",
related = {
"Rasterizer:getGlyphCount"
},
variants = {
{
arguments = {
{
name = "...",
type = "*",
description = "Strings (sets of characters) or numbers (character codes) to check for."
}
},
returns = {
{
name = "hasGlyphs",
type = "boolean",
description = "true if the Rasterizer can rasterize all of the supplied characters, false otherwise."
}
}
}
}
}
}
},
{
name = "SoundData",
summary = "An object that holds raw audio samples.",
description = "A SoundData stores raw audio samples that make up a sound file. You can use `Source` objects to play SoundData.",
key = "SoundData",
module = "lovr.data",
constructors = {
"lovr.data.newSoundData",
"AudioStream:decode",
"Microphone:getData"
},
methods = {
{
name = "getBitDepth",
summary = "Get the bit depth of the SoundData.",
description = "Returns the number of bits taken up by each sample in the SoundData. Higher bit depths mean the sound is higher quality and takes up more space. This is usually 8 or 16.",
key = "SoundData:getBitDepth",
module = "lovr.data",
related = {
"AudioStream:getBitDepth",
"Source:getBitDepth"
},
variants = {
{
arguments = {},
returns = {
{
name = "bitDepth",
type = "number",
description = "The size of each sample, in bits."
}
}
}
}
},
{
name = "getChannelCount",
summary = "Get the number of channels in the SoundData.",
description = "Returns the number of channels in the SoundData. Mono sounds have 1 channel and stereo sounds have 2 channels.",
key = "SoundData:getChannelCount",
module = "lovr.data",
notes = "It's important to keep in mind the channel count if you're using `SoundData:getSample` and `SoundData:setSample`. The SoundData stores its samples in an \"interleaved\" manner, meaning the samples from different channels are stored next to each other.\n\nIf you want to get the 3rd sample of the second channel of a stereo sound, you would use sample number 5, since samples start at zero and `(sample * channelCount) + channelIndex = 5`.",
variants = {
{
arguments = {},
returns = {
{
name = "channels",
type = "number",
description = "The number of channels."
}
}
}
},
related = {
"AudioStream:getChannelCount",
"Source:getChannelCount"
}
},
{
name = "getDuration",
summary = "Get the duration of the SoundData.",
description = "Returns the duration of the sound data in seconds.",
key = "SoundData:getDuration",
module = "lovr.data",
related = {
"SoundData:getSampleCount",
"AudioStream:getDuration",
"Source:getDuration"
},
variants = {
{
arguments = {},
returns = {
{
name = "duration",
type = "number",
description = "The duration of the sound."
}
}
}
}
},
{
name = "getSample",
summary = "Get a sample from the SoundData.",
description = "Returns a single sample from the SoundData. Sample indices start at 0, and the returned value will be between -1 and 1.",
key = "SoundData:getSample",
module = "lovr.data",
notes = "Note that samples for individual channels in stereo sounds are stored next to each other.",
variants = {
{
arguments = {
{
name = "index",
type = "number",
description = "The index of the sample to get."
}
},
returns = {
{
name = "value",
type = "number",
description = "A number indicating the value of the sample at the given index."
}
}
}
},
related = {
"SoundData:getSampleCount",
"SoundData:getSampleRate"
}
},
{
name = "getSampleCount",
summary = "Get the number of samples stored in the SoundData.",
description = "Returns the number of samples in the SoundData (per channel).",
key = "SoundData:getSampleCount",
module = "lovr.data",
related = {
"SoundData:getSample",
"SoundData:getChannelCount",
"Source:getDuration"
},
variants = {
{
arguments = {},
returns = {
{
name = "samples",
type = "number",
description = "The total number of channels per channel."
}
}
}
}
},
{
name = "getSampleRate",
summary = "Get the sample rate of the SoundData.",
description = "Returns the number of samples per second in the SoundData. This is usually a high number like 44100.",
key = "SoundData:getSampleRate",
module = "lovr.data",
related = {
"AudioStream:getSampleRate",
"Source:getSampleRate"
},
variants = {
{
arguments = {},
returns = {
{
name = "frequency",
type = "number",
description = "The number of samples per second in the SoundData."
}
}
}
}
},
{
name = "setSample",
summary = "Modify a sample in the SoundData.",
description = "Modify a single sample in the SoundData. Sample indices start at zero, and samples should be between -1 and 1.",
key = "SoundData:setSample",
module = "lovr.data",
notes = "Note that samples for individual channels in stereo sounds are stored next to each other.",
variants = {
{
arguments = {
{
name = "index",
type = "number",
description = "The index of the sample to set."
},
{
name = "value",
type = "number",
description = "The new value of the sample."
}
},
returns = {}
}
},
related = {
"SoundData:getSampleCount",
"SoundData:getSampleRate"
}
}
}
},
{
name = "TextureData",
summary = "An object that stores pixel data for Textures.",
description = "A TextureData stores raw 2D pixel info for `Texture`s. It has a width, height, and format. The TextureData 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`.\n\nUsually you can just use Textures, but TextureData 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.",
key = "TextureData",
module = "lovr.data",
constructors = {
"lovr.data.newTextureData",
"Canvas:newTextureData"
},
methods = {
{
name = "encode",
summary = "Encode the TextureData as png and write it to a file.",
description = "Encodes the TextureData to png and writes it to the specified file.",
key = "TextureData:encode",
module = "lovr.data",
variants = {
{
arguments = {
{
name = "filename",
type = "string",
description = "The file to write the png data to."
}
},
returns = {
{
name = "success",
type = "boolean",
description = "Whether or not the file was successfully written to."
}
}
}
}
},
{
name = "getDimensions",
summary = "Get the dimensions of the TextureData.",
description = "Returns the dimensions of the TextureData, in pixels.",
key = "TextureData:getDimensions",
module = "lovr.data",
related = {
"TextureData:getWidth",
"TextureData:getHeight",
"Texture:getDimensions"
},
variants = {
{
arguments = {},
returns = {
{
name = "width",
type = "number",
description = "The width of the TextureData, in pixels."
},
{
name = "height",
type = "number",
description = "The height of the TextureData, in pixels."
}
}
}
}
},
{
name = "getFormat",
summary = "Get the pixel format of the TextureData.",
description = "Returns the format of the TextureData.",
key = "TextureData:getFormat",
module = "lovr.data",
related = {
"TextureFormat",
"Texture:getFormat"
},
variants = {
{
arguments = {},
returns = {
{
name = "format",
type = "TextureFormat",
description = "The format of the TextureData."
}
}
}
}
},
{
name = "getHeight",
summary = "Get the height of the TextureData.",
description = "Returns the height of the TextureData, in pixels.",
key = "TextureData:getHeight",
module = "lovr.data",
related = {
"TextureData:getWidth",
"TextureData:getDimensions",
"Texture:getHeight"
},
variants = {
{
arguments = {},
returns = {
{
name = "height",
type = "number",
description = "The height of the TextureData, in pixels."
}
}
}
}
},
{
name = "getPixel",
summary = "Get the value of a pixel of the TextureData.",
description = "Returns the value of a pixel of the TextureData.",
key = "TextureData:getPixel",
module = "lovr.data",
notes = "The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`.",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x coordinate of the pixel to get (0-indexed)."
},
{
name = "y",
type = "number",
description = "The y coordinate of the pixel to get (0-indexed)."
}
},
returns = {
{
name = "r",
type = "number",
description = "The red component of the pixel, from 0.0 to 1.0."
},
{
name = "g",
type = "number",
description = "The green component of the pixel, from 0.0 to 1.0."
},
{
name = "b",
type = "number",
description = "The blue component of the pixel, from 0.0 to 1.0."
},
{
name = "a",
type = "number",
description = "The alpha component of the pixel, from 0.0 to 1.0."
}
}
}
},
related = {
"TextureData:setPixel",
"Texture:replacePixels",
"TextureFormat"
}
},
{
name = "getWidth",
summary = "Get the width of the TextureData.",
description = "Returns the width of the TextureData, in pixels.",
key = "TextureData:getWidth",
module = "lovr.data",
related = {
"TextureData:getHeight",
"TextureData:getDimensions",
"Texture:getWidth"
},
variants = {
{
arguments = {},
returns = {
{
name = "width",
type = "number",
description = "The width of the TextureData, in pixels."
}
}
}
}
},
{
name = "paste",
summary = "Copy pixels from another TextureData to this one.",
description = "Copies a rectangle of pixels from one TextureData to this one.",
key = "TextureData:paste",
module = "lovr.data",
notes = "The two TextureData must have the same pixel format.\n\nCompressed TextureData cannot be copied.\n\nThe rectangle cannot go outside the dimensions of the source or destination textures.",
variants = {
{
arguments = {
{
name = "source",
type = "TextureData",
description = "The TextureData to copy pixels from."
},
{
name = "x",
type = "number",
description = "The x coordinate to paste to (0-indexed).",
default = "0"
},
{
name = "y",
type = "number",
description = "The y coordinate to paste to (0-indexed).",
default = "0"
},
{
name = "fromX",
type = "number",
description = "The x coordinate in the source to paste from (0-indexed).",
default = "0"
},
{
name = "fromY",
type = "number",
description = "The y coordinate in the source to paste from (0-indexed).",
default = "0"
},
{
name = "width",
type = "number",
description = "The width of the region to copy.",
default = "source:getWidth()"
},
{
name = "height",
type = "number",
description = "The height of the region to copy.",
default = "source:getHeight()"
}
},
returns = {}
}
},
related = {
"Texture:replacePixels",
"TextureData:getPixel",
"TextureData:setPixel"
}
},
{
name = "setPixel",
summary = "Set the value of a pixel of the TextureData.",
description = "Sets the value of a pixel of the TextureData.",
key = "TextureData:setPixel",
module = "lovr.data",
notes = "The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`.",
variants = {
{
arguments = {
{
name = "x",
type = "number",
description = "The x coordinate of the pixel to set (0-indexed)."
},
{
name = "y",
type = "number",
description = "The y coordinate of the pixel to set (0-indexed)."
},
{
name = "r",
type = "number",
description = "The red component of the pixel, from 0.0 to 1.0."
},
{
name = "g",
type = "number",
description = "The green component of the pixel, from 0.0 to 1.0."
},
{
name = "b",
type = "number",
description = "The blue component of the pixel, from 0.0 to 1.0."
},
{
name = "a",
type = "number",
description = "The alpha component of the pixel, from 0.0 to 1.0.",
default = "1.0"
}
},
returns = {}
}
},
related = {
"TextureData:getPixel",
"Texture:replacePixels",
"TextureFormat"
}
}
}
}
},
functions = {
{
name = "newAudioStream",
summary = "Create a new AudioStream.",
description = "Creates a new AudioStream. Right now, the only supported audio format is Ogg Vorbis (.ogg).",
key = "lovr.data.newAudioStream",
module = "lovr.data",
variants = {
{
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the audio file to load."
},
{
name = "bufferSize",
type = "number",
description = "The size of the stream's audio buffer, in samples.",
default = "4096"
}
},
returns = {
{
name = "audioStream",
type = "AudioStream",
description = "The new AudioStream."
}
}
},
{
arguments = {
{
name = "blob",
type = "Blob",
description = "The Blob containing audio data to decode."
},
{
name = "bufferSize",
type = "number",
description = "The size of the stream's audio buffer, in samples.",
default = "4096"
}
},
returns = {
{
name = "audioStream",
type = "AudioStream",
description = "The new AudioStream."
}
}
}
}
},
{
name = "newBlob",
summary = "Create a new Blob.",
description = "Creates a new Blob.",
key = "lovr.data.newBlob",
module = "lovr.data",
related = {
"lovr.filesystem.newBlob"
},
variants = {
{
arguments = {
{
name = "size",
type = "number",
description = "The amount of data to allocate for the Blob, in bytes. All of the bytes will be filled with zeroes."
},
{
name = "name",
type = "string",
description = "A name for the Blob (used in error messages)",
default = "''"
}
},
returns = {
{
name = "blob",
type = "Blob",
description = "The new Blob."
}
}
},
{
arguments = {
{
name = "contents",
type = "string",
description = "A string to use for the Blob's contents."
},
{
name = "name",
type = "string",
description = "A name for the Blob (used in error messages)",
default = "''"
}
},
returns = {
{
name = "blob",
type = "Blob",
description = "The new Blob."
}
}
},
{
arguments = {
{
name = "source",
type = "Blob",
description = "A Blob to copy the contents from."
},
{
name = "name",
type = "string",
description = "A name for the Blob (used in error messages)",
default = "''"
}
},
returns = {
{
name = "blob",
type = "Blob",
description = "The new Blob."
}
}
}
}
},
{
name = "newModelData",
summary = "Create a new ModelData.",
description = "Loads a 3D model from a file. The supported 3D file formats are OBJ and glTF.",
key = "lovr.data.newModelData",
module = "lovr.data",
variants = {
{
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the model to load."
}
},
returns = {
{
name = "modelData",
type = "ModelData",
description = "The new ModelData."
}
}
},
{
arguments = {
{
name = "blob",
type = "Blob",
description = "The Blob containing data for a model to decode."
}
},
returns = {
{
name = "modelData",
type = "ModelData",
description = "The new ModelData."
}
}
}
}
},
{
name = "newRasterizer",
summary = "Create a new Rasterizer.",
description = "Creates a new Rasterizer from a TTF file.",
key = "lovr.data.newRasterizer",
module = "lovr.data",
variants = {
{
description = "Create a Rasterizer for the default font included with LÖVR (Varela Round).",
arguments = {
{
name = "size",
type = "number",
description = "The resolution to render the fonts at, in pixels. Higher resolutions use more memory and processing power but may provide better quality results for some fonts/situations.",
default = "32"
}
},
returns = {
{
name = "rasterizer",
type = "Rasterizer",
description = "The new Rasterizer."
}
}
},
{
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the font file to load."
},
{
name = "size",
type = "number",
description = "The resolution to render the fonts at, in pixels. Higher resolutions use more memory and processing power but may provide better quality results for some fonts/situations.",
default = "32"
}
},
returns = {
{
name = "rasterizer",
type = "Rasterizer",
description = "The new Rasterizer."
}
}
},
{
arguments = {
{
name = "blob",
type = "Blob",
description = "The Blob containing font data."
},
{
name = "size",
type = "number",
description = "The resolution to render the fonts at, in pixels. Higher resolutions use more memory and processing power but may provide better quality results for some fonts/situations.",
default = "32"
}
},
returns = {
{
name = "rasterizer",
type = "Rasterizer",
description = "The new Rasterizer."
}
}
}
}
},
{
name = "newSoundData",
summary = "Create a new SoundData.",
description = "Creates a new SoundData. You can pass a filename or Blob to decode, an existing AudioStream to decode audio samples from, or you can create an empty SoundData that can hold a certain number of samples.",
key = "lovr.data.newSoundData",
module = "lovr.data",
variants = {
{
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the sound to decode."
}
},
returns = {
{
name = "soundData",
type = "SoundData",
description = "The new SoundData."
}
}
},
{
arguments = {
{
name = "samples",
type = "number",
description = "The total number of samples for each channel."
},
{
name = "sampleRate",
type = "number",
description = "The number of samples per second.",
default = "44100"
},
{
name = "bitDepth",
type = "number",
description = "The number of bits stored for each sample.",
default = "16"
},
{
name = "channels",
type = "number",
description = "The number of channels in the sound (1 for mono, 2 for stereo).",
default = "2"
}
},
returns = {
{
name = "soundData",
type = "SoundData",
description = "The new SoundData."
}
}
},
{
arguments = {},
returns = {
{
name = "soundData",
type = "SoundData",
description = "The new SoundData."
}
}
},
{
arguments = {
{
name = "blob",
type = "string",
description = "The Blob containing compressed sound data to decode."
}
},
returns = {
{
name = "soundData",
type = "SoundData",
description = "The new SoundData."
}
}
}
}
},
{
name = "newTextureData",
summary = "Create a new TextureData.",
description = "Creates a new TextureData. 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.",
key = "lovr.data.newTextureData",
module = "lovr.data",
notes = "Right now the supported image file formats are png, jpg, hdr, dds (DXT1, DXT3, DXT5), ktx, and astc.",
variants = {
{
description = "Load image data from a file.",
arguments = {
{
name = "filename",
type = "string",
description = "The filename of the image to load."
},
{
name = "flip",
type = "boolean",
description = "Whether to vertically flip the image on load. This should be true for normal textures, and false for textures that are going to be used in a cubemap.",
default = "true"
}
},
returns = {
{
name = "textureData",
type = "TextureData",
description = "The new TextureData."
}
}
},
{
description = "Create an empty TextureData, initializing all pixel values to 0 (transparent black).",
arguments = {
{
name = "width",
type = "number",
description = "The width of the texture."
},
{
name = "height",
type = "number",
description = "The height of the texture."
},
{
name = "format",
type = "TextureFormat",
description = "The format of the texture's pixels.",
default = "rgba"
}
},
returns = {
{
name = "textureData",
type = "TextureData",
description = "The new TextureData."
}
}
},
{
description = "Decode image data from a Blob.",
arguments = {
{
name = "blob",
type = "Blob",
description = "The Blob containing image data to decode."
},
{
name = "flip",
type = "boolean",
description = "Whether to vertically flip the image on load. This should be true for normal textures, and false for textures that are going to be used in a cubemap.",
default = "true"
}
},
returns = {
{
name = "textureData",
type = "TextureData",
description = "The new TextureData."
}
}
}
}
}
},
enums = {}
},
{
name = "event",
tag = "modules",
summary = "Handles events from the operating system.",
description = "The `lovr.event` module handles events from the operating system.\n\nDue to its low-level nature, it's rare to use `lovr.event` in simple projects.",
key = "lovr.event",
enums = {},
examples = {
{
description = "Adding a custom event.",
code = "function lovr.load()\n lovr.handlers['customevent'] = function(a, b, c)\n print('custom event handled with args:', a, b, c)\n end\n\n lovr.event.push('customevent', 1, 2, 3)\nend"
}
},
functions = {
{
name = "clear",
summary = "Clear the event queue.",
description = "Clears the event queue, removing any unprocessed events.",
key = "lovr.event.clear",
module = "lovr.event",
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "poll",
summary = "Iterate over unprocessed events in the queue.",
description = "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.",
key = "lovr.event.poll",
module = "lovr.event",
variants = {
{
arguments = {},
returns = {
{
name = "iterator",
type = "function",
description = "The iterator function, usable in a for loop.",
arguments = {},
returns = {}
}
}
}
}
},
{
name = "pump",
summary = "Pump new events into the queue for processing.",
description = "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`.",
key = "lovr.event.pump",
module = "lovr.event",
related = {
"lovr.event.poll"
},
variants = {
{
arguments = {},
returns = {}
}
}
},
{
name = "push",
summary = "Manually push an event onto the queue.",
description = "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.",
key = "lovr.event.push",
module = "lovr.event",
notes = "Only nil, booleans, numbers, strings, and LÖVR objects are supported types for event data.",
variants = {
{
arguments = {
{
name = "name",
type = "string",
description = "The name of the event."
},
{
name = "...",
type = "*",
description = "The arguments for the event. Currently, up to 4 are supported."
}
},
returns = {}
}
},
related = {
"lovr.event.poll",
"lovr.event.quit"
}
},
{
name = "quit",
summary = "Quit the application.",
description = "Pushes an event to quit or restart the application. 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. Alternatively, the string 'restart' can be used to cause LÖVR to reload the project.",
key = "lovr.event.quit",
module = "lovr.event",
notes = "This function is equivalent to calling `lovr.event.push('quit',