Manipulator: helper API for drawing custom shapes

This exposes 2 methods for manipulators:
- new_custom_shape
- draw_custom_shape

This can be used for script authors to create and re-use shapes
without dealing with lower level API's.

release/scripts/modules/bpy_types.py

@@ -620,6 +620,68 @@ class Manipulator(StructRNA, metaclass=OrderedMeta):
 
     target_set_handler = _bpy._rna_manipulator_target_set_handler
 
+    # Convenience wrappers around private `_gawain` module.
+    def draw_custom_shape(self, shape, *, matrix=None, select_id=None):
+        """
+        Draw a shape created form :class:`bpy.types.Manipulator.draw_custom_shape`.
+
+        :arg shape: The cached shape to draw.
+        :type shape: Undefined.
+        :arg matrix: 4x4 matrix, when not given
+           :class:`bpy.types.Manipulator.matrix_world` is used.
+        :type matrix: :class:`mathutils.Matrix`
+        :arg select_id: The selection id.
+           Only use when drawing within :class:`bpy.types.Manipulator.draw_select`.
+        :type select_it: int
+        """
+        import gpu
+
+        if matrix is None:
+            matrix = self.matrix_world
+
+        if select_id is not None:
+            gpu.select.load_id(select_id)
+        else:
+            if self.is_highlight:
+                color = (*self.color_highlight, self.alpha_highlight)
+            else:
+                color = (*self.color, self.alpha)
+            shape.uniform_f32("color", *color)
+
+        with gpu.matrix.push_pop():
+            gpu.matrix.multiply_matrix(matrix)
+            shape.draw()
+
+    @staticmethod
+    def new_custom_shape(type, verts):
+        """
+        Create a new shape that can be passed to :class:`bpy.types.Manipulator.draw_custom_shape`.
+
+        :arg type: The type of shape to create in (POINTS, LINES, TRIS, LINE_STRIP).
+        :type type: string
+        :arg verts: Coordinates.
+        :type verts: sequence of of 2D or 3D coordinates.
+        :arg display_name: Optional callback that takes the full path, returns the name to display.
+        :type display_name: Callable that takes a string and returns a string.
+        :return: The newly created shape.
+        :rtype: Undefined (it may change).
+        """
+        from _gawain.types import (
+            Gwn_Batch,
+            Gwn_VertBuf,
+            Gwn_VertFormat,
+        )
+        dims = len(verts[0])
+        if dims not in {2, 3}:
+            raise ValueError("Expected 2D or 3D vertex")
+        fmt = Gwn_VertFormat()
+        pos_id = fmt.attr_add(id="pos", comp_type='F32', len=dims, fetch_mode='FLOAT')
+        vbo = Gwn_VertBuf(len=len(verts), format=fmt)
+        vbo.fill(id=pos_id, data=verts)
+        batch = Gwn_Batch(type=type, buf=vbo)
+        batch.program_set_builtin('3D_UNIFORM_COLOR' if dims == 3 else '2D_UNIFORM_COLOR')
+        return batch
+
 
 # Only defined so operators members can be used by accessing self.order
 # with doc generation 'self.properties.bl_rna.properties' can fail