Add class descriptions for Texture2DArray, CubemapArray and ImageTextureLayered, plus overhaul TextureLayered

Co-authored-by: Clay John <claynjohn@gmail.com>

7 files changed, 28 insertions, 7 deletions

diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml
index ee28675d89..cbb58a3e1e 100644
--- a/doc/classes/BaseMaterial3D.xml
+++ b/doc/classes/BaseMaterial3D.xml
@@ -28,7 +28,7 @@
 			<return type="Texture2D" />
 			<param index="0" name="param" type="int" enum="BaseMaterial3D.TextureParam" />
 			<description>
-				Returns the [Texture] associated with the specified [enum TextureParam].
+				Returns the [Texture2D] associated with the specified [enum TextureParam].
 			</description>
 		</method>
 		<method name="set_feature">
diff --git a/doc/classes/Cubemap.xml b/doc/classes/Cubemap.xml
index 7173388027..0cdebeda95 100644
--- a/doc/classes/Cubemap.xml
+++ b/doc/classes/Cubemap.xml
@@ -4,9 +4,9 @@
 		6-sided texture typically used in 3D rendering.
 	</brief_description>
 	<description>
-		A cubemap is a 6-sided texture typically used for faking reflections in 3D rendering. It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods.
+		A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections (see [ReflectionProbe]) in 3D rendering. It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods.
 		This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of Cubemap resources.
-		[b]Note:[/b] Godot doesn't support using cubemaps as a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cube map to an equirectangular sky map.
+		[b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/CubemapArray.xml b/doc/classes/CubemapArray.xml
index 4fca842b5a..7f001155e4 100644
--- a/doc/classes/CubemapArray.xml
+++ b/doc/classes/CubemapArray.xml
@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="CubemapArray" inherits="ImageTextureLayered" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		A single composite texture resource which consists of multiple [Cubemap]s.
 	</brief_description>
 	<description>
+		[CubemapArray]s are made of an array of [Cubemap]s. Accordingly, like [Cubemap]s they are made of multiple textures the amount of which must be divisible by 6 (one image for each face of the cube). The primary benefit of [CubemapArray]s is that they can be accessed in shader code using a single texture reference. In other words, you can pass multiple [Cubemap]s into a shader using a single [CubemapArray].
+		Generally, [CubemapArray]s provide a more efficent way for storing multiple [Cubemap]s, than storing multiple [Cubemap]s themselves in an array.
+		Internally Godot, uses [CubemapArray]s for many effects including the [Sky], if you set [member ProjectSettings.rendering/reflections/sky_reflections/texture_array_reflections] to [code]true[/code].
+		[b]Note:[/b] [CubemapArray] is not supported in the OpenGL 3 rendering backend.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/ImageTextureLayered.xml b/doc/classes/ImageTextureLayered.xml
index f5b338542b..f5786f070a 100644
--- a/doc/classes/ImageTextureLayered.xml
+++ b/doc/classes/ImageTextureLayered.xml
@@ -11,6 +11,8 @@
 			<return type="int" enum="Error" />
 			<param index="0" name="images" type="Image[]" />
 			<description>
+				Creates an [ImageTextureLayered] from an array of [Image]s. The first image decides the width, height, image format and mipmapping setting. The other images must have the same width, height, image format and mipmapping setting.
+				Each [Image] represents one [code]layer[/code].
 			</description>
 		</method>
 		<method name="update_layer">
@@ -18,6 +20,10 @@
 			<param index="0" name="image" type="Image" />
 			<param index="1" name="layer" type="int" />
 			<description>
+				Replaces the existing [Image] data at the given [code]layer[/code] with this new image.
+				The given [Image] must have the same width, height, image format and mipmapping setting (a [code]bool[/code] value) as the rest of the referenced images.
+				If the image format is unsupported, it will be decompressed and converted to a similar and supported [enum Image.Format].
+				The update is immediate: synced with the draw.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/PanoramaSkyMaterial.xml b/doc/classes/PanoramaSkyMaterial.xml
index 21c7f29585..0c27037f28 100644
--- a/doc/classes/PanoramaSkyMaterial.xml
+++ b/doc/classes/PanoramaSkyMaterial.xml
@@ -4,9 +4,9 @@
 		A [Material] used with [Sky] to draw a background texture.
 	</brief_description>
 	<description>
-		A resource referenced in a [Sky] that is used to draw a background. The Panorama sky material functions similar to skyboxes in other engines, except it uses an equirectangular sky map instead of a cube map.
+		A resource referenced in a [Sky] that is used to draw a background. The Panorama sky material functions similar to skyboxes in other engines, except it uses an equirectangular sky map instead of a cubemap.
 		Using an HDR panorama is strongly recommended for accurate, high-quality reflections. Godot supports the Radiance HDR ([code].hdr[/code]) and OpenEXR ([code].exr[/code]) image formats for this purpose.
-		You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cube map to an equirectangular sky map.
+		You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/Texture2DArray.xml b/doc/classes/Texture2DArray.xml
index 6f059b5fbf..113f37f974 100644
--- a/doc/classes/Texture2DArray.xml
+++ b/doc/classes/Texture2DArray.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Texture2DArray" inherits="ImageTextureLayered" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		A single texture resource which consists of multiple, separate images. Each image has the same dimensions and number of mipmap levels.
 	</brief_description>
 	<description>
+		A Texture2DArray is different from a Texture3D: The Texture2DArray does not support trilinear interpolation between the [Image]s, i.e. no blending.
+		A Texture2DArray is also different from an [AtlasTexture]: In a Texture2DArray, all images are treated separately. In an atlas, the regions (i.e. the single images) can be of different sizes. Furthermore, you usually need to add a padding around the regions, to prevent accidental UV mapping to more than one region. The same goes for mipmapping: Mipmap chains are handled separately for each layer. In an atlas, the slicing has to be done manually in the fragment shader.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/TextureLayered.xml b/doc/classes/TextureLayered.xml
index 7b528e2082..5e6afcbc5c 100644
--- a/doc/classes/TextureLayered.xml
+++ b/doc/classes/TextureLayered.xml
@@ -1,10 +1,15 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="TextureLayered" inherits="Texture" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Base class for 3D texture types.
+		Base class for texture types which contain the data of multiple [Image]s. Each image is of the same size and format.
 	</brief_description>
 	<description>
-		Base class for [Texture2DArray], [Cubemap] and [CubemapArray]. Cannot be used directly, but contains all the functions necessary for accessing the derived resource types. Data is set on a per-layer basis. For [Texture2DArray]s, the layer specifies the array layer.
+		Base class for [Texture2DArray], [Cubemap] and [CubemapArray]. Cannot be used directly, but contains all the functions necessary for accessing the derived resource types.
+		Data is set on a per-layer basis. For [Texture2DArray]s, the layer specifies the array layer.
+		All images need to have the same width, height and number of mipmap levels.
+		A [TextureLayered] can be loaded with [code]method ResourceFormatLoader.load[/code].
+		To create such a texture file yourself, re-import your image files using the Godot Editor import presets.
+		Internally, Godot maps these files to their respective counterparts in the target rendering driver (GLES3, Vulkan).
 	</description>
 	<tutorials>
 	</tutorials>
@@ -72,6 +77,7 @@
 		<method name="get_layers" qualifiers="const">
 			<return type="int" />
 			<description>
+				Returns the number of referenced [Image]s.
 			</description>
 		</method>
 		<method name="get_width" qualifiers="const">
@@ -83,6 +89,7 @@
 		<method name="has_mipmaps" qualifiers="const">
 			<return type="bool" />
 			<description>
+				Returns [code]true[/code] if the layers have generated mipmaps.
 			</description>
 		</method>
 	</methods>