Mesa (gallium-array-textures): gallium: interface changes for array textures and related cleanups

Roland Scheidegger sroland at kemper.freedesktop.org
Thu Jun 3 13:05:38 PDT 2010


Module: Mesa
Branch: gallium-array-textures
Commit: 4a4d927609b62b4d7fb9dffa35158afe282f277b
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=4a4d927609b62b4d7fb9dffa35158afe282f277b

Author: Roland Scheidegger <sroland at vmware.com>
Date:   Thu Jun  3 22:02:44 2010 +0200

gallium: interface changes for array textures and related cleanups

This patch introduces array textures to gallium (note they are not immediately
usable without the associated changes to the shader side).
Also, this abandons pipe_subresource in favor of using level and layer
parameters since the distinction between several faces (which was part of
pipe_subresource for cube textures) and several z slices (which were not part
of pipe_subresource but instead part of pipe_box where appropriate for 3d
textures) is gone at the resource level.
Textures, be it array, cube, or 3d, now use a "unified" set of parameters,
there is no distinction between array members, cube faces, or 3d zslices.
This is unlike d3d10, whose subresource index includes layer information for
array textures, but which considers all z slices of a 3d texture to be part
of the same subresource.
In contrast to d3d10, OpenGL though reuses old 2d and 3d function entry points
for 1d and 2d array textures, respectively, which also implies that for instance
it is possible to specify all layers of a 2d array texture at once (note that
this is not possible for cube maps, which use the 2d entry points, although
it is possible for cube map arrays, which aren't supported yet in gallium).
This should possibly make drivers a bit simpler, and also get rid of mutually
exclusive parameters in some functions (as z and face were exclusive), one
potential downside would be that 3d array textures could not easily be supported
without reverting this, but those are nowhere to be seen.

Also along with adjusting to new parameters, rename get_tex_surface /
tex_surface_destroy to create_surface / surface_destroy and move them from
screen to context, which reflects much better what those do (they are analogous
to create_sampler_view / sampler_view_destroy).

PIPE_CAP_ARRAY_TEXTURES is used to indicate if a driver supports all of this
functionality (that is, both sampling from array texture as well as use a range
of layers as a render target, with selecting the layer from the geometry shader).

---

 src/gallium/docs/source/context.rst  |   32 ++++++++++++++++---
 src/gallium/include/pipe/p_context.h |   57 +++++++++++++++++++++-------------
 src/gallium/include/pipe/p_defines.h |   13 +++++---
 src/gallium/include/pipe/p_screen.h  |   12 -------
 src/gallium/include/pipe/p_state.h   |   24 +++++---------
 5 files changed, 78 insertions(+), 60 deletions(-)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 27d352b..16c7e83 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -79,7 +79,14 @@ in the result register. For example, ``swizzle_r`` specifies what is going to be
 placed in first component of result register.
 
 The ``first_level`` and ``last_level`` fields of sampler view template specify
-the LOD range the texture is going to be constrained to.
+the LOD range the texture is going to be constrained to. Note that these
+values are in addition to the respective min_lod, max_lod values in the
+pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
+level used for sampling from the resource is effectively the fifth).
+
+The ``first_layer`` and ``last_layer`` fields specify the layer range the
+texture is going to be constrained to. Similar to the LOD range, this is added
+to the array index which is used for sampling.
 
 * ``set_fragment_sampler_views`` binds an array of sampler views to
   fragment shader stage. Every binding point acquires a reference
@@ -98,6 +105,22 @@ the LOD range the texture is going to be constrained to.
 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
   to associated texture.
 
+Surfaces
+^^^^^^^^
+
+These are the means to use resources as color render targets or depthstencil
+attachments. To create one, specify the mip level, the range of layers, and
+the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
+Note that layer values are in addition to what is indicated by the geometry
+shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
+shader indicates index 2, the 5th layer of the resource will be used). These
+first_layer and last_layer parameters will only be used for 1d array, 2d array,
+cube, and 3d textures otherwise they are 0.
+
+* ``create_surface`` creates a new surface.
+
+* ``surface_destroy`` destroys a surface and releases its reference to the
+  associated resource.
 
 Clearing
 ^^^^^^^^
@@ -281,10 +304,9 @@ These methods operate directly on ``pipe_resource`` objects, and stand
 apart from any 3D state in the context.  Blitting functionality may be
 moved to a separate abstraction at some point in the future.
 
-``resource_copy_region`` blits a region of a subresource of a resource to a
-region of another subresource of a resource, provided that both resources have the
-same format. The source and destination may be the same resource, but overlapping
-blits are not permitted.
+``resource_copy_region`` blits a region of a resource to a region of another
+resource, provided that both resources have the same format. The source and
+destination may be the same resource, but overlapping blits are not permitted.
 
 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
 one. Formats and dimensions must match. This function must be present if a driver
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 3e082be..73a7331 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -249,12 +249,11 @@ struct pipe_context {
     */
    void (*resource_copy_region)(struct pipe_context *pipe,
                                 struct pipe_resource *dst,
-                                struct pipe_subresource subdst,
+                                unsigned level,
                                 unsigned dstx, unsigned dsty, unsigned dstz,
                                 struct pipe_resource *src,
-                                struct pipe_subresource subsrc,
-                                unsigned srcx, unsigned srcy, unsigned srcz,
-                                unsigned width, unsigned height);
+                                unsigned level,
+                                const struct pipe_box *);
 
    /**
     * Resolve a multisampled resource into a non-multisampled one.
@@ -262,9 +261,9 @@ struct pipe_context {
     */
    void (*resource_resolve)(struct pipe_context *pipe,
                             struct pipe_resource *dst,
-                            struct pipe_subresource subdst,
+                            unsigned layer,
                             struct pipe_resource *src,
-                            struct pipe_subresource subsrc);
+                            unsigned layer);
 
    /*@}*/
 
@@ -321,13 +320,13 @@ struct pipe_context {
     * PIPE_REFERENCED_FOR_READ | PIPE_REFERENCED_FOR_WRITE.
     * \param pipe  context whose unflushed hw commands will be checked.
     * \param texture  texture to check.
-    * \param face  cubemap face. Use 0 for non-cubemap texture.
     * \param level  mipmap level.
+    * \param layer  cubemap face, 2d array or 3d slice. Use -1 for any layer, 0 otherwise.
     * \return mask of PIPE_REFERENCED_FOR_READ/WRITE or PIPE_UNREFERENCED
     */
    unsigned int (*is_resource_referenced)(struct pipe_context *pipe,
-					  struct pipe_resource *texture,
-					  unsigned face, unsigned level);
+                                          struct pipe_resource *texture,
+                                          unsigned level, unsigned layer);
 
    /**
     * Create a view on a texture to be used by a shader stage.
@@ -341,20 +340,34 @@ struct pipe_context {
 
 
    /**
+    * Get a surface which is a "view" into a resource, used by
+    * render target / depth stencil stages.
+    * \param usage  bitmaks of PIPE_BIND_* flags
+    */
+   struct pipe_surface *(*create_surface)(struct pipe_screen *,
+                                          struct pipe_resource *resource,
+                                          unsigned level,
+                                          unsigned first_layer,
+                                          unsigned last_layer,
+                                          unsigned usage );
+
+   void (*surface_destroy)(struct pipe_surface *);
+
+   /**
     * Get a transfer object for transferring data to/from a texture.
     *
     * Transfers are (by default) context-private and allow uploads to be
     * interleaved with
     */
    struct pipe_transfer *(*get_transfer)(struct pipe_context *,
-					 struct pipe_resource *resource,
-					 struct pipe_subresource,
-					 unsigned usage,  /* a combination of PIPE_TRANSFER_x */
-					 const struct pipe_box *);
+                                         struct pipe_resource *resource,
+                                         unsigned level,
+                                         unsigned usage,  /* a combination of PIPE_TRANSFER_x */
+                                         const struct pipe_box *);
 
    void (*transfer_destroy)(struct pipe_context *,
-                                struct pipe_transfer *);
-   
+                            struct pipe_transfer *);
+
    void *(*transfer_map)( struct pipe_context *,
                           struct pipe_transfer *transfer );
 
@@ -374,13 +387,13 @@ struct pipe_context {
     * pointer.  XXX: strides??
     */
    void (*transfer_inline_write)( struct pipe_context *,
-				  struct pipe_resource *,
-				  struct pipe_subresource,
-				  unsigned usage, /* a combination of PIPE_TRANSFER_x */
-				  const struct pipe_box *,
-				  const void *data,
-				  unsigned stride,
-				  unsigned slice_stride);
+                                  struct pipe_resource *,
+                                  unsigned level,
+                                  unsigned usage, /* a combination of PIPE_TRANSFER_x */
+                                  const struct pipe_box *,
+                                  const void *data,
+                                  unsigned stride,
+                                  unsigned layer_stride);
 
 };
 
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 420649c..b49c152 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -137,11 +137,13 @@ enum pipe_error {
 
 /** Texture types */
 enum pipe_texture_target {
-   PIPE_BUFFER       = 0,
-   PIPE_TEXTURE_1D   = 1,
-   PIPE_TEXTURE_2D   = 2,
-   PIPE_TEXTURE_3D   = 3,
-   PIPE_TEXTURE_CUBE = 4,
+   PIPE_BUFFER           = 0,
+   PIPE_TEXTURE_1D       = 1,
+   PIPE_TEXTURE_2D       = 2,
+   PIPE_TEXTURE_3D       = 3,
+   PIPE_TEXTURE_CUBE     = 4,
+   PIPE_TEXTURE_1D_ARRAY = 5,
+   PIPE_TEXTURE_2D_ARRAY = 6,
    PIPE_MAX_TEXTURE_TYPES
 };
 
@@ -455,6 +457,7 @@ enum pipe_cap {
    /** different blend funcs per rendertarget */
    PIPE_CAP_INDEP_BLEND_FUNC,
    PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE,
+   PIPE_CAP_ARRAY_TEXTURES,
    PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT,
    PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT,
    PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER,
diff --git a/src/gallium/include/pipe/p_screen.h b/src/gallium/include/pipe/p_screen.h
index 21f428e..97bd8d9 100644
--- a/src/gallium/include/pipe/p_screen.h
+++ b/src/gallium/include/pipe/p_screen.h
@@ -130,18 +130,6 @@ struct pipe_screen {
    void (*resource_destroy)(struct pipe_screen *,
 			    struct pipe_resource *pt);
 
-   /** Get a 2D surface which is a "view" into a texture
-    * \param usage  bitmaks of PIPE_BIND_* flags
-    */
-   struct pipe_surface *(*get_tex_surface)(struct pipe_screen *,
-                                           struct pipe_resource *resource,
-                                           unsigned face, unsigned level,
-                                           unsigned zslice,
-                                           unsigned usage );
-
-   void (*tex_surface_destroy)(struct pipe_surface *);
-   
-
 
    /**
     * Create a buffer that wraps user-space data.
diff --git a/src/gallium/include/pipe/p_state.h b/src/gallium/include/pipe/p_state.h
index 5255b20..0fdf408 100644
--- a/src/gallium/include/pipe/p_state.h
+++ b/src/gallium/include/pipe/p_state.h
@@ -285,9 +285,9 @@ struct pipe_surface
    unsigned offset;              /**< offset from start of buffer, in bytes */
    unsigned usage;               /**< bitmask of PIPE_BIND_x */
 
-   unsigned zslice;
-   unsigned face;
    unsigned level;
+   unsigned first_layer;
+   unsigned last_layer;
 };
 
 
@@ -302,6 +302,8 @@ struct pipe_sampler_view
    struct pipe_context *context; /**< context this view belongs to */
    unsigned first_level:8;       /**< first mipmap level */
    unsigned last_level:8;        /**< last mipmap level */
+   unsigned first_layer:16;      /**< first layer to use for array textures */
+   unsigned last_layer:16;       /**< last layer to use for array textures */
    unsigned swizzle_r:3;         /**< PIPE_SWIZZLE_x for red component */
    unsigned swizzle_g:3;         /**< PIPE_SWIZZLE_x for green component */
    unsigned swizzle_b:3;         /**< PIPE_SWIZZLE_x for blue component */
@@ -341,18 +343,8 @@ struct pipe_resource
    unsigned nr_samples:8;    /**< for multisampled surfaces, nr of samples */
    unsigned usage:8;         /**< PIPE_USAGE_x (not a bitmask) */
 
-   unsigned bind;	     /**< bitmask of PIPE_BIND_x */
-   unsigned flags;	     /**< bitmask of PIPE_RESOURCE_FLAG_x */
-};
-
-
-/**
- * Extra indexing info for (cube) texture resources.
- */
-struct pipe_subresource
-{
-   unsigned face:16;
-   unsigned level:16;
+   unsigned bind;            /**< bitmask of PIPE_BIND_x */
+   unsigned flags;           /**< bitmask of PIPE_RESOURCE_FLAG_x */
 };
 
 
@@ -362,11 +354,11 @@ struct pipe_subresource
 struct pipe_transfer
 {
    struct pipe_resource *resource; /**< resource to transfer to/from  */
-   struct pipe_subresource sr;
+   unsigned level;
    enum pipe_transfer_usage usage;
    struct pipe_box box;
    unsigned stride;
-   unsigned slice_stride;
+   unsigned layer_stride;
    void *data;
 };
 



More information about the mesa-commit mailing list