gallium: add blit into the interface

Tested-by: Michel Dänzer <michel.daenzer@amd.com>
Reviewed-by: Brian Paul <brianp@vmware.com>

src/gallium/docs/source/context.rst

@@ -434,6 +434,15 @@ formats, i.e., formats for which copying the bytes from the source resource
 unmodified to the destination resource will achieve the same effect of a
 textured quad blitter.. The source and destination may be the same resource,
 but overlapping blits are not permitted.
+This can be considered the equivalent of a CPU memcpy.
+
+``blit`` blits a region of a resource to a region of another resource, including
+scaling, format conversion, and up-/downsampling, as well as
+a destination clip rectangle (scissors).
+As opposed to manually drawing a textured quad, this lets the pipe driver choose
+the optimal method for blitting (like using a special 2D engine), and usually
+offers, for example, accelerated stencil-only copies even where
+PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
 
 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
 one. Their formats must match. This function must be present if a driver

src/gallium/include/pipe/p_context.h

@@ -39,6 +39,7 @@ extern "C" {
 
 struct pipe_blend_color;
 struct pipe_blend_state;
+struct pipe_blit_info;
 struct pipe_box;
 struct pipe_clip_state;
 struct pipe_constant_buffer;
@@ -297,6 +298,12 @@ struct pipe_context {
                                 unsigned src_level,
                                 const struct pipe_box *src_box);
 
+   /* Optimal hardware path for blitting pixels.
+    * Scaling, format conversion, up- and downsampling (resolve) are allowed.
+    */
+   void (*blit)(struct pipe_context *pipe,
+                const struct pipe_blit_info *info);
+
    /**
     * Resolve a multisampled resource into a non-multisampled one.
     * Source and destination must be of the same format.

src/gallium/include/pipe/p_state.h

@@ -564,6 +564,27 @@ struct pipe_draw_info
 };
 
 
+/**
+ * Information to describe a blit call.
+ */
+struct pipe_blit_info
+{
+   struct {
+      struct pipe_resource *resource;
+      unsigned level;
+      struct pipe_box box; /**< negative width, height only legal for src */
+      /* For pipe_surface-like format casting: */
+      enum pipe_format format; /**< must be supported for sampling (src)
+                               or rendering (dst), ZS is always supported */
+   } dst, src;
+
+   unsigned mask; /**< bitmask of PIPE_MASK_R/G/B/A/Z/S */
+   unsigned filter; /**< PIPE_TEX_FILTER_* */
+
+   boolean scissor_enable;
+   struct pipe_scissor_state scissor;
+};
+
 /**
  * Information to describe a resource_resolve call.
  */