From 0f82a0f569223f9e726f9571464ab13bef01e66c Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Mon, 5 Jun 2023 16:39:59 +0200
Subject: [PATCH] Document the InitialAction enum in RenderingDevice

This also improves the documentation for the FinalAction enum,
and fixes an incorrect comment in the RenderingDevice header.
---
 doc/classes/RenderingDevice.xml      |  6 ++++++
 servers/rendering/rendering_device.h | 18 +++++++++---------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml
index 26a7ae6aca1..2e92eac2a51 100644
--- a/doc/classes/RenderingDevice.xml
+++ b/doc/classes/RenderingDevice.xml
@@ -2044,16 +2044,22 @@
 		<constant name="DYNAMIC_STATE_STENCIL_REFERENCE" value="64" enum="PipelineDynamicStateFlags" is_bitfield="true">
 		</constant>
 		<constant name="INITIAL_ACTION_CLEAR" value="0" enum="InitialAction">
+			Start rendering and clear the whole framebuffer.
 		</constant>
 		<constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction">
+			Start rendering and clear the framebuffer in the specified region.
 		</constant>
 		<constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="2" enum="InitialAction">
+			Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously.
 		</constant>
 		<constant name="INITIAL_ACTION_KEEP" value="3" enum="InitialAction">
+			Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition.
 		</constant>
 		<constant name="INITIAL_ACTION_DROP" value="4" enum="InitialAction">
+			Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color.
 		</constant>
 		<constant name="INITIAL_ACTION_CONTINUE" value="5" enum="InitialAction">
+			Continue rendering. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously.
 		</constant>
 		<constant name="INITIAL_ACTION_MAX" value="6" enum="InitialAction">
 			Represents the size of the [enum InitialAction] enum.
diff --git a/servers/rendering/rendering_device.h b/servers/rendering/rendering_device.h
index 82f89daa6df..ae7de2b8f25 100644
--- a/servers/rendering/rendering_device.h
+++ b/servers/rendering/rendering_device.h
@@ -1138,19 +1138,19 @@ public:
 	/********************/
 
 	enum InitialAction {
-		INITIAL_ACTION_CLEAR, //start rendering and clear the whole framebuffer (region or not) (supply params)
-		INITIAL_ACTION_CLEAR_REGION, //start rendering and clear the framebuffer in the specified region (supply params)
-		INITIAL_ACTION_CLEAR_REGION_CONTINUE, //continue rendering and clear the framebuffer in the specified region (supply params)
-		INITIAL_ACTION_KEEP, //start rendering, but keep attached color texture contents (depth will be cleared)
-		INITIAL_ACTION_DROP, //start rendering, ignore what is there, just write above it
-		INITIAL_ACTION_CONTINUE, //continue rendering (framebuffer must have been left in "continue" state as final action previously)
+		INITIAL_ACTION_CLEAR, // Start rendering and clear the whole framebuffer.
+		INITIAL_ACTION_CLEAR_REGION, // Start rendering and clear the framebuffer in the specified region.
+		INITIAL_ACTION_CLEAR_REGION_CONTINUE, // Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in `FINAL_ACTION_CONTINUE` state as the final action previously.
+		INITIAL_ACTION_KEEP, // Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition.
+		INITIAL_ACTION_DROP, // Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color.
+		INITIAL_ACTION_CONTINUE, // Continue rendering. Framebuffer must have been left in `FINAL_ACTION_CONTINUE` state as the final action previously.
 		INITIAL_ACTION_MAX
 	};
 
 	enum FinalAction {
-		FINAL_ACTION_READ, //will no longer render to it, allows attached textures to be read again, but depth buffer contents will be dropped (Can't be read from)
-		FINAL_ACTION_DISCARD, // discard contents after rendering
-		FINAL_ACTION_CONTINUE, //will continue rendering later, attached textures can't be read until re-bound with "finish"
+		FINAL_ACTION_READ, // Store the texture for reading and make it read-only if it has the `TEXTURE_USAGE_SAMPLING_BIT` bit (only applies to color, depth and stencil attachments).
+		FINAL_ACTION_DISCARD, // Discard the texture data and make it read-only if it has the `TEXTURE_USAGE_SAMPLING_BIT` bit (only applies to color, depth and stencil attachments).
+		FINAL_ACTION_CONTINUE, // Store the texture and continue for further processing. Similar to `FINAL_ACTION_READ`, but does not make the texture read-only if it has the `TEXTURE_USAGE_SAMPLING_BIT` bit.
 		FINAL_ACTION_MAX
 	};