pvr: Add comments documenting large/normal clear words.

Signed-off-by: Karmjit Mahil <Karmjit.Mahil@imgtec.com>
Reviewed-by: Frank Binns <frank.binns@imgtec.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/20055>

src/imagination/vulkan/pvr_clear.c

@@ -337,7 +337,15 @@ VkResult pvr_device_init_graphics_static_clear_state(struct pvr_device *device)
     * dedup this?
     */
 
-   /* TODO: Figure out where the 4 * sizeof(uint32_t) comes from. */
+   /* The large clear state words cover the max framebuffer. The normal clear
+    * state words cover only half (since 3 indices are passed, forming a single
+    * triangle, instead of 4) and are used when the render area fits within a
+    * quarter of the max framebuffer, i.e. fit within the single triangle.
+    */
+   /* 4 * sizeof(uint32_t) because of the 4 pixel output regs. */
+   /* TODO: Replace 4 * sizeof(uint32_t) with a defines from the compiler or
+    * hook up the value directly to it using some compiler info.
+    */
    pvr_pack_clear_vdm_state(&device->pdevice->dev_info,
                             &state->pds,
                             pds_program.temps_used,
@@ -346,7 +354,6 @@ VkResult pvr_device_init_graphics_static_clear_state(struct pvr_device *device)
                             1,
                             state->vdm_words);
 
-   /* TODO: Figure out where the 4 * sizeof(uint32_t) comes from. */
    pvr_pack_clear_vdm_state(&device->pdevice->dev_info,
                             &state->pds,
                             pds_program.temps_used,

src/imagination/vulkan/pvr_cmd_buffer.c

@@ -2363,6 +2363,20 @@ pvr_cmd_buffer_set_clear_values(struct pvr_cmd_buffer *cmd_buffer,
    return VK_SUCCESS;
 }
 
+/**
+ * \brief Indicates whether to use the large or normal clear state words.
+ *
+ * If the current render area can fit within a quarter of the max framebuffer
+ * that the device is capable of, we can use the normal clear state words,
+ * otherwise the large clear state words are needed.
+ *
+ * The requirement of a quarter of the max framebuffer comes from the index
+ * count used in the normal clear state words and the vertices uploaded at
+ * device creation.
+ *
+ * \param[in] cmd_buffer The command buffer for the clear.
+ * \return true if large clear state words are required.
+ */
 static bool
 pvr_is_large_clear_required(const struct pvr_cmd_buffer *const cmd_buffer)
 {