Merge pull request #71991 from clayjohn/RS-docs

Fill out more sections in RenderingServer and RenderingDevice

doc/classes/RenderingDevice.xml

@@ -1,8 +1,14 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="RenderingDevice" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstraction for working with modern low-level graphics APIs.
 	</brief_description>
 	<description>
+		[RenderingDevice] is an abstraction for working with modern low-level graphics APIs such as Vulkan.
+		On startup, Godot creates a global [RenderingDevice] which can be retrieved using [method RenderingServer.get_rendering_device]. This global RenderingDevice performs drawing to the screen.
+		Internally, [RenderingDevice] is used in Godot to provide support for several modern low-level graphics APIs while reducing the amount of code duplication required.
+		[b]Local RenderingDevices:[/b] Using [method RenderingServer.create_local_rendering_device], you can create "secondary" rendering devices to perform drawing and GPU compute operations on separate threads.
+		[b]Note:[/b] [RenderingDevice] is not available when running in headless mode or when using the OpenGL renderer.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -1162,20 +1168,28 @@
 		<constant name="BARRIER_MASK_NO_BARRIER" value="8" enum="BarrierMask" is_bitfield="true">
 		</constant>
 		<constant name="TEXTURE_TYPE_1D" value="0" enum="TextureType">
+			1-dimensional texture.
 		</constant>
 		<constant name="TEXTURE_TYPE_2D" value="1" enum="TextureType">
+			2-dimensional texture.
 		</constant>
 		<constant name="TEXTURE_TYPE_3D" value="2" enum="TextureType">
+			3-dimensional texture.
 		</constant>
 		<constant name="TEXTURE_TYPE_CUBE" value="3" enum="TextureType">
+			[Cubemap] texture.
 		</constant>
 		<constant name="TEXTURE_TYPE_1D_ARRAY" value="4" enum="TextureType">
+			Array of 1-dimensional textures.
 		</constant>
 		<constant name="TEXTURE_TYPE_2D_ARRAY" value="5" enum="TextureType">
+			Array of 2-dimensional textures.
 		</constant>
 		<constant name="TEXTURE_TYPE_CUBE_ARRAY" value="6" enum="TextureType">
+			Array of [Cubemap] textures.
 		</constant>
 		<constant name="TEXTURE_TYPE_MAX" value="7" enum="TextureType">
+			Represents the size of the [enum TextureType] enum.
 		</constant>
 		<constant name="TEXTURE_SAMPLES_1" value="0" enum="TextureSamples">
 		</constant>
@@ -1192,6 +1206,7 @@
 		<constant name="TEXTURE_SAMPLES_64" value="6" enum="TextureSamples">
 		</constant>
 		<constant name="TEXTURE_SAMPLES_MAX" value="7" enum="TextureSamples">
+			Represents the size of the [enum TextureSamples] enum.
 		</constant>
 		<constant name="TEXTURE_USAGE_SAMPLING_BIT" value="1" enum="TextureUsageBits" is_bitfield="true">
 		</constant>
@@ -1236,8 +1251,10 @@
 		<constant name="TEXTURE_SLICE_3D" value="2" enum="TextureSliceType">
 		</constant>
 		<constant name="SAMPLER_FILTER_NEAREST" value="0" enum="SamplerFilter">
+			Nearest-neighbor sampler filtering. Sampling at higher resolutions than the source will result in a pixelated look.
 		</constant>
 		<constant name="SAMPLER_FILTER_LINEAR" value="1" enum="SamplerFilter">
+			Bilinear sampler filtering. Sampling at higher resolutions than the source will result in a blurry look.
 		</constant>
 		<constant name="SAMPLER_REPEAT_MODE_REPEAT" value="0" enum="SamplerRepeatMode">
 		</constant>
@@ -1298,8 +1315,10 @@
 		<constant name="UNIFORM_TYPE_MAX" value="10" enum="UniformType">
 		</constant>
 		<constant name="RENDER_PRIMITIVE_POINTS" value="0" enum="RenderPrimitive">
+			Point rendering primitive (with constant size, regardless of distance from camera).
 		</constant>
 		<constant name="RENDER_PRIMITIVE_LINES" value="1" enum="RenderPrimitive">
+			Line rendering primitive.
 		</constant>
 		<constant name="RENDER_PRIMITIVE_LINES_WITH_ADJACENCY" value="2" enum="RenderPrimitive">
 		</constant>
@@ -1380,6 +1399,7 @@
 		<constant name="LOGIC_OP_NO_OP" value="5" enum="LogicOperation">
 		</constant>
 		<constant name="LOGIC_OP_XOR" value="6" enum="LogicOperation">
+			Exclusive or (XOR) logic operation.
 		</constant>
 		<constant name="LOGIC_OP_OR" value="7" enum="LogicOperation">
 		</constant>
@@ -1442,16 +1462,22 @@
 		<constant name="BLEND_FACTOR_MAX" value="19" enum="BlendFactor">
 		</constant>
 		<constant name="BLEND_OP_ADD" value="0" enum="BlendOperation">
+			Additive blending operation ([code]source + destination[/code]).
 		</constant>
 		<constant name="BLEND_OP_SUBTRACT" value="1" enum="BlendOperation">
+			Subtractive blending operation ([code]source - destination[/code]).
 		</constant>
 		<constant name="BLEND_OP_REVERSE_SUBTRACT" value="2" enum="BlendOperation">
+			Reverse subtractive blending operation ([code]destination - source[/code]).
 		</constant>
 		<constant name="BLEND_OP_MINIMUM" value="3" enum="BlendOperation">
+			Minimum blending operation (keep the lowest value of the two).
 		</constant>
 		<constant name="BLEND_OP_MAXIMUM" value="4" enum="BlendOperation">
+			Maximum blending operation (keep the highest value of the two).
 		</constant>
 		<constant name="BLEND_OP_MAX" value="5" enum="BlendOperation">
+			Represents the size of the [enum BlendOperation] enum.
 		</constant>
 		<constant name="DYNAMIC_STATE_LINE_WIDTH" value="1" enum="PipelineDynamicStateFlags" is_bitfield="true">
 		</constant>
@@ -1544,12 +1570,16 @@
 		<constant name="LIMIT_MAX_TEXTURE_ARRAY_LAYERS" value="10" enum="Limit">
 		</constant>
 		<constant name="LIMIT_MAX_TEXTURE_SIZE_1D" value="11" enum="Limit">
+			Maximum supported 1-dimensional texture size (in pixels on a single axis).
 		</constant>
 		<constant name="LIMIT_MAX_TEXTURE_SIZE_2D" value="12" enum="Limit">
+			Maximum supported 2-dimensional texture size (in pixels on a single axis).
 		</constant>
 		<constant name="LIMIT_MAX_TEXTURE_SIZE_3D" value="13" enum="Limit">
+			Maximum supported 3-dimensional texture size (in pixels on a single axis).
 		</constant>
 		<constant name="LIMIT_MAX_TEXTURE_SIZE_CUBE" value="14" enum="Limit">
+			Maximum supported cubemap texture size (in pixels on a single axis of a single face).
 		</constant>
 		<constant name="LIMIT_MAX_TEXTURES_PER_SHADER_STAGE" value="15" enum="Limit">
 		</constant>
@@ -1596,14 +1626,19 @@
 		<constant name="LIMIT_MAX_VIEWPORT_DIMENSIONS_Y" value="36" enum="Limit">
 		</constant>
 		<constant name="MEMORY_TEXTURES" value="0" enum="MemoryType">
+			Memory taken by textures.
 		</constant>
 		<constant name="MEMORY_BUFFERS" value="1" enum="MemoryType">
+			Memory taken by buffers.
 		</constant>
 		<constant name="MEMORY_TOTAL" value="2" enum="MemoryType">
+			Total memory taken. This is greater than the sum of [constant MEMORY_TEXTURES] and [constant MEMORY_BUFFERS], as it also includes miscellaneous memory usage.
 		</constant>
 		<constant name="INVALID_ID" value="-1">
+			Returned by functions that return an ID if a value is invalid.
 		</constant>
 		<constant name="INVALID_FORMAT_ID" value="-1">
+			Returned by functions that return a format ID if a value is invalid.
 		</constant>
 	</constants>
 </class>

doc/classes/RenderingServer.xml

@@ -4,10 +4,10 @@
 		Server for anything visible.
 	</brief_description>
 	<description>
-		Server for anything visible. The rendering server is the API backend for everything visible. The whole scene system mounts on it to display.
+		The rendering server is the API backend for everything visible. The whole scene system mounts on it to display.
 		The rendering server is completely opaque, the internals are entirely implementation specific and cannot be accessed.
-		The rendering server can be used to bypass the scene system entirely.
-		Resources are created using the [code]*_create[/code] functions.
+		The rendering server can be used to bypass the scene/[Node] system entirely.
+		Resources are created using the [code]*_create[/code] functions. These functions return [RID]s which are not references to the objects themselves, but opaque [i]pointers[/i] towards these objects.
 		All objects are drawn to a viewport. You can use the [Viewport] attached to the [SceneTree] or you can create one yourself with [method viewport_create]. When using a custom scenario or canvas, the scenario or canvas needs to be attached to the viewport using [method viewport_set_scenario] or [method viewport_attach_canvas].
 		In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the rendering server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world_3d]. Otherwise, a scenario can be created with [method scenario_create].
 		Similarly, in 2D, a canvas is needed to draw all canvas items.
@@ -25,6 +25,7 @@
 			<param index="1" name="material_overrides" type="RID[]" />
 			<param index="2" name="image_size" type="Vector2i" />
 			<description>
+				Bakes the material data of the Mesh passed in the [param base] parameter with optional [param material_overrides] to a set of [Image]s of size [param image_size]. Returns an array of [Image]s containing material properties as specified in [enum BakeChannels].
 			</description>
 		</method>
 		<method name="camera_attributes_create">
@@ -43,6 +44,7 @@
 			<param index="4" name="speed" type="float" />
 			<param index="5" name="scale" type="float" />
 			<description>
+				Sets the parameters to use with the auto-exposure effect. These parameters take on the same meaning as their counterparts in [CameraAttributes] and [CameraAttributesPractical].
 			</description>
 		</method>
 		<method name="camera_attributes_set_dof_blur">
@@ -56,12 +58,14 @@
 			<param index="6" name="near_transition" type="float" />
 			<param index="7" name="amount" type="float" />
 			<description>
+				Sets the parameters to use with the dof blur effect. These parameters take on the same meaning as their counterparts in [CameraAttributesPractical].
 			</description>
 		</method>
 		<method name="camera_attributes_set_dof_blur_bokeh_shape">
 			<return type="void" />
 			<param index="0" name="shape" type="int" enum="RenderingServer.DOFBokehShape" />
 			<description>
+				Sets the shape of the dof bokeh pattern. Different shapes may be used to acheive artistic effect, or to meet performance targets. For more detail on available options see [enum DOFBokehShape].
 			</description>
 		</method>
 		<method name="camera_attributes_set_dof_blur_quality">
@@ -69,6 +73,7 @@
 			<param index="0" name="quality" type="int" enum="RenderingServer.DOFBlurQuality" />
 			<param index="1" name="use_jitter" type="bool" />
 			<description>
+				Sets the quality level of the dof blur effect to one of the options in [enum DOFBlurQuality]. [param use_jitter] can be used to jitter samples taken during the blur pass to hide artifacts at the cost of looking more fuzzy.
 			</description>
 		</method>
 		<method name="camera_attributes_set_exposure">
@@ -102,6 +107,7 @@
 			<param index="0" name="camera" type="RID" />
 			<param index="1" name="effects" type="RID" />
 			<description>
+				Sets the camera_attributes created with [method camera_attributes_create] to the given camera.
 			</description>
 		</method>
 		<method name="camera_set_cull_mask">
@@ -192,6 +198,7 @@
 			<param index="2" name="radius" type="float" />
 			<param index="3" name="color" type="Color" />
 			<description>
+				Draws a circle on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_circle].
 			</description>
 		</method>
 		<method name="canvas_item_add_clip_ignore">
@@ -199,6 +206,7 @@
 			<param index="0" name="item" type="RID" />
 			<param index="1" name="ignore" type="bool" />
 			<description>
+				If [param ignore] is [code]true[/code], ignore clipping on items drawn with this canvas item until this is called again with [param ignore] set to false.
 			</description>
 		</method>
 		<method name="canvas_item_add_lcd_texture_rect_region">
@@ -209,6 +217,7 @@
 			<param index="3" name="src_rect" type="Rect2" />
 			<param index="4" name="modulate" type="Color" />
 			<description>
+				See also [method CanvasItem.draw_lcd_texture_rect_region].
 			</description>
 		</method>
 		<method name="canvas_item_add_line">
@@ -220,6 +229,7 @@
 			<param index="4" name="width" type="float" default="-1.0" />
 			<param index="5" name="antialiased" type="bool" default="false" />
 			<description>
+				Draws a line on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_line].
 			</description>
 		</method>
 		<method name="canvas_item_add_mesh">
@@ -230,6 +240,7 @@
 			<param index="3" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
 			<param index="4" name="texture" type="RID" />
 			<description>
+				Draws a mesh created with [method mesh_create] with given [param transform], [param modulate] color, and [param texture]. This is used internally by [MeshInstance2D].
 			</description>
 		</method>
 		<method name="canvas_item_add_msdf_texture_rect_region">
@@ -243,6 +254,7 @@
 			<param index="6" name="px_range" type="float" default="1.0" />
 			<param index="7" name="scale" type="float" default="1.0" />
 			<description>
+				See also [method CanvasItem.draw_msdf_texture_rect_region].
 			</description>
 		</method>
 		<method name="canvas_item_add_multimesh">
@@ -251,6 +263,7 @@
 			<param index="1" name="mesh" type="RID" />
 			<param index="2" name="texture" type="RID" />
 			<description>
+				Draws a 2D [MultiMesh] on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_multimesh].
 			</description>
 		</method>
 		<method name="canvas_item_add_nine_patch">
@@ -266,6 +279,7 @@
 			<param index="8" name="draw_center" type="bool" default="true" />
 			<param index="9" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
 			<description>
+				Draws a nine-patch rectangle on the [CanvasItem] pointed to by the [param item] [RID].
 			</description>
 		</method>
 		<method name="canvas_item_add_particles">
@@ -274,6 +288,7 @@
 			<param index="1" name="particles" type="RID" />
 			<param index="2" name="texture" type="RID" />
 			<description>
+				Draws particles on the [CanvasItem] pointed to by the [param item] [RID].
 			</description>
 		</method>
 		<method name="canvas_item_add_polygon">
@@ -284,6 +299,7 @@
 			<param index="3" name="uvs" type="PackedVector2Array" default="PackedVector2Array()" />
 			<param index="4" name="texture" type="RID" />
 			<description>
+				Draws a 2D polygon on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_polygon].
 			</description>
 		</method>
 		<method name="canvas_item_add_polyline">
@@ -294,6 +310,7 @@
 			<param index="3" name="width" type="float" default="-1.0" />
 			<param index="4" name="antialiased" type="bool" default="false" />
 			<description>
+				Draws a 2D polyline on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_polyline].
 			</description>
 		</method>
 		<method name="canvas_item_add_primitive">
@@ -304,6 +321,7 @@
 			<param index="3" name="uvs" type="PackedVector2Array" />
 			<param index="4" name="texture" type="RID" />
 			<description>
+				Draws a 2D primitive on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_primitive].
 			</description>
 		</method>
 		<method name="canvas_item_add_rect">
@@ -312,6 +330,7 @@
 			<param index="1" name="rect" type="Rect2" />
 			<param index="2" name="color" type="Color" />
 			<description>
+				Draws a rectangle on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_rect].
 			</description>
 		</method>
 		<method name="canvas_item_add_set_transform">
@@ -319,6 +338,7 @@
 			<param index="0" name="item" type="RID" />
 			<param index="1" name="transform" type="Transform2D" />
 			<description>
+				Sets a [Transform2D] that will be used to transform subsequent canvas item commands.
 			</description>
 		</method>
 		<method name="canvas_item_add_texture_rect">
@@ -368,6 +388,7 @@
 		<method name="canvas_item_create">
 			<return type="RID" />
 			<description>
+				Creates a new [CanvasItem] instance and returns its [RID].
 			</description>
 		</method>
 		<method name="canvas_item_set_canvas_group_mode">
@@ -1792,6 +1813,7 @@
 		<method name="lightmap_create">
 			<return type="RID" />
 			<description>
+				Creates a new [LightmapGI] instance.
 			</description>
 		</method>
 		<method name="lightmap_get_probe_capture_bsp_tree" qualifiers="const">
@@ -4565,12 +4587,16 @@
 			Fade-in the given instance's dependencies when reaching its visibility range limits.
 		</constant>
 		<constant name="BAKE_CHANNEL_ALBEDO_ALPHA" value="0" enum="BakeChannels">
+			Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains albedo color in the [code].rgb[/code] channels and alpha in the [code].a[/code] channel.
 		</constant>
 		<constant name="BAKE_CHANNEL_NORMAL" value="1" enum="BakeChannels">
+			Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains the per-pixel normal of the object in the [code].rgb[/code] channels and nothing in the [code].a[/code] channel. The per-pixel normal is encoded as [code]normal * 0.5 + 0.5[/code].
 		</constant>
 		<constant name="BAKE_CHANNEL_ORM" value="2" enum="BakeChannels">
+			Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains ambient occlusion (from material and decals only) in the [code].r[/code] channel, roughness in the [code].g[/code] channel, metallic in the [code].b[/code] channel and sub surface scattering amount in the [code].a[/code] channel.
 		</constant>
 		<constant name="BAKE_CHANNEL_EMISSION" value="3" enum="BakeChannels">
+			Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBAH] and contains emission color in the [code].rgb[/code] channels and nothing in the [code].a[/code] channel.
 		</constant>
 		<constant name="CANVAS_TEXTURE_CHANNEL_DIFFUSE" value="0" enum="CanvasTextureChannel">
 		</constant>