{{newin|[[11.0]]|110|type=function}}
Creates a new [[TextureType|volume]] (3D) [[Image]].
{{newobjectnotice}}

Volume images are 3D textures with width, height, and depth. They can't be rendered directly, they can only be used in [[Shader]] code (and sent to the shader via [[Shader:send]]).

To use a volume image in a Shader, it must be declared as a <code>VolumeImage</code> or <code>sampler3D</code> type (instead of <code>Image</code> or <code>sampler2D</code>). The <code>Texel(VolumeImage image, vec3 texcoords)</code> shader function must be used to get pixel colors from the volume image. The vec3 argument is a normalized texture coordinate with the z component representing the depth to sample at (ranging from [0, 1]).

Volume images are typically used as lookup tables in shaders for color grading, for example, because sampling using a texture coordinate that is partway in between two pixels can interpolate across all 3 dimensions in the volume image, resulting in a smooth gradient even when a small-sized volume image is used as the lookup table.

[[love.graphics.newArrayImage|Array images]] are a much better choice than volume images for storing multiple different sprites in a single array image for directly drawing them.

== Function ==
Creates a volume Image given multiple image files with matching dimensions.
=== Synopsis ===
<source lang="lua">
image = love.graphics.newVolumeImage( layers, settings )
</source>
=== Arguments ===
{{param|table|layers|A table containing filepaths to images (or [[File]], [[FileData]], [[ImageData]], or [[CompressedImageData]] objects), in an array. A table of tables can also be given, where each sub-table represents a single mipmap level and contains all layers for that mipmap.}}
{{param|table|settings (nil)|Optional table of settings to configure the volume image, containing the following fields:}}
{{subparam|boolean|mipmaps (false)|True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a [[PixelFormat|compressed texture]] format.}}
{{subparam|boolean|linear (false)|True to treat the image's pixels as linear instead of sRGB, when [[love.graphics.isGammaCorrect|gamma correct rendering]] is enabled. Most images are authored as sRGB.}}
=== Returns ===
{{param|Image|image|A volume Image object.}}

== Notes ==
Volume images are not supported on some older mobile devices. Use [[love.graphics.getTextureTypes]] to check at runtime.

== See Also ==
* [[parent::love.graphics]]
* [[Constructs::Image]]
* [[TextureType]]
[[Category:Functions]]
[[Sub-Category::Object Creation| ]]
{{#set:Description=Creates a new [[TextureType|volume]] [[Image]].}}
== Other Languages ==
{{i18n|love.graphics.newVolumeImage}}