ImmediateModeShapeDrawer Object-centric documentation example additions
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.
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