ImmediateModeShapeDrawer Object-centric documentation example additions

Avatar
  • updated
  • Completed

ImmediateModeShapeDrawer added in 3.0.0 allows us to easily create a component for wrapping Immediate Mode draw calls.


It lends itself very nicely to use cases where you want to draw stuff relative to the GameObject that the component is attached to.

I think it would be useful to expand the provided example with the following additions:

[ExecuteAlways] public class MyScript : ImmediateModeShapeDrawer 
{
    public override void DrawShapes( Camera cam ) 
    {
        // 1. Respect Camera culling mask
        if ((cam.cullingMask & 1 << gameObject.layer) == 0) 
            return;

        using( Draw.Command( cam ) ) 
        {
            // set up all static parameters. these are used for all following Draw.Line calls
            Draw.LineGeometry = LineGeometry.Volumetric3D;
            Draw.LineThicknessSpace = ThicknessSpace.Pixels;
            Draw.LineThickness = 4; // 4px wide

            // 2. Draw in object local space
            Draw.Matrix = transform.localToWorldMatrix;

            // draw lines
            Draw.Line( Vector3.zero, Vector3.right,   Color.red   );
            Draw.Line( Vector3.zero, Vector3.up,      Color.green );
            Draw.Line( Vector3.zero, Vector3.forward, Color.blue  );
        }
    }
}

1. Respect Camera culling mask

Since the implementation of ImmediateModeShapeDrawer calls DrawShapes in a Camera.onPreRender (or RenderPipelineManager.beginCameraRendering) callback, it does not benefit from object-specific culling by default (as Unity's OnPreRender() does). This isn't immediately obvious and so specifically including it in an example can help clarify some confusion there

2. Draw in object local space

It would similarly be useful if the user is using ImmediateModeShapeDrawer to add visual elements to the GameObject they are attaching it to (which I would argue would be a very common use-case for such a helper component), for Draw calls to be done in the object's local space.

While it is already mentioned in the Shapes.Draw (drawing matrix) section of the documentation, I think it is still worth including in a full example for clarity.

I think these two additions would benefit most use cases of ImmediateModeShapeDrawer and so are worthwhile additions to the standard example in the documentation, while still being small enough to not bloat the example unecessarily.

Reporting a bug? please specify Unity version:
3.0.0
Reporting a bug? please specify Shapes version:
Reporting a bug? please specify Render Pipeline:
Built-in render pipeline
Pinned replies
Avatar
Freya Holmér creator
  • Answer
  • Completed

I feel like adding the camera culling mask as a feature you can toggle on/off in the shape drawer would make sense, I'll do that for 3.0.1, but I don't want to add more confusion to the example, especially when the using() syntax is probably new to many as it is

Just added the matrix to the docs though! it's a useful concept, especially since I talk about it below too, good to include an example I think

Avatar
Freya Holmér creator
  • Answer
  • Completed

I feel like adding the camera culling mask as a feature you can toggle on/off in the shape drawer would make sense, I'll do that for 3.0.1, but I don't want to add more confusion to the example, especially when the using() syntax is probably new to many as it is

Just added the matrix to the docs though! it's a useful concept, especially since I talk about it below too, good to include an example I think