Mesa (main): panfrost: Document arguments to tiling routines

[GitLab Mirror]

Module: Mesa
Branch: main
Commit: 944049dedc0d36d62ac8c50ad92c0cc49acdb6f0
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=944049dedc0d36d62ac8c50ad92c0cc49acdb6f0

Author: Alyssa Rosenzweig <alyssa at collabora.com>
Date:   Thu Apr 14 11:48:41 2022 -0400

panfrost: Document arguments to tiling routines

The exact semantics of these routines are subtle, although they match what
Gallium wants. We're about to add unit tests. Add some comments that make it
obvious what it is we expect these routines to do. (In particular, it's not a
general region-of-interest copy, it's a region-of-interest of the tiled image
and the entire linear staging image.)

Signed-off-by: Alyssa Rosenzweig <alyssa at collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/15803>

---

 src/panfrost/shared/pan_tiling.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/panfrost/shared/pan_tiling.h b/src/panfrost/shared/pan_tiling.h
index d8591e6dbdd..5e35fe8dfc1 100644
--- a/src/panfrost/shared/pan_tiling.h
+++ b/src/panfrost/shared/pan_tiling.h
@@ -30,6 +30,19 @@
 #include <stdint.h>
 #include <util/format/u_format.h>
 
+/**
+ * Load a rectangular region from a tiled image to a linear staging image.
+ *
+ * @dst Linear destination
+ * @src Tiled source
+ * @x Region of interest of source in pixels, aligned to block size
+ * @y Region of interest of source in pixels, aligned to block size
+ * @z Region of interest of source in pixels, aligned to block size
+ * @w Region of interest of source in pixels, aligned to block size
+ * @dst_stride Stride in bytes of linear destination
+ * @src_stride Stride in bytes of tiled source
+ * @format Format of the source and destination image
+ */
 void panfrost_load_tiled_image(void *dst, const void *src,
                                unsigned x, unsigned y,
                                unsigned w, unsigned h,
@@ -37,6 +50,19 @@ void panfrost_load_tiled_image(void *dst, const void *src,
                                uint32_t src_stride,
                                enum pipe_format format);
 
+/**
+ * Store a linear staging image to a rectangular region of a tiled image.
+ *
+ * @dst Tiled destination
+ * @src Linear source
+ * @x Region of interest of destination in pixels, aligned to block size
+ * @y Region of interest of destination in pixels, aligned to block size
+ * @z Region of interest of destination in pixels, aligned to block size
+ * @w Region of interest of destination in pixels, aligned to block size
+ * @dst_stride Stride in bytes of tiled destination
+ * @src_stride Stride in bytes of linear source
+ * @format Format of the source and destination image
+ */
 void panfrost_store_tiled_image(void *dst, const void *src,
                                 unsigned x, unsigned y,
                                 unsigned w, unsigned h,