BorrowedTorch.SceneGizmo
1.2.2
Prefix Reserved
dotnet add package BorrowedTorch.SceneGizmo --version 1.2.2
NuGet\Install-Package BorrowedTorch.SceneGizmo -Version 1.2.2
<PackageReference Include="BorrowedTorch.SceneGizmo" Version="1.2.2" />
<PackageVersion Include="BorrowedTorch.SceneGizmo" Version="1.2.2" />
<PackageReference Include="BorrowedTorch.SceneGizmo" />
paket add BorrowedTorch.SceneGizmo --version 1.2.2
#r "nuget: BorrowedTorch.SceneGizmo, 1.2.2"
#:package BorrowedTorch.SceneGizmo@1.2.2
#addin nuget:?package=BorrowedTorch.SceneGizmo&version=1.2.2
#tool nuget:?package=BorrowedTorch.SceneGizmo&version=1.2.2
BorrowedTorch.SceneGizmo
A world-orientation gizmo for MonoGame: the small X / Y / Z widget in the corner of an editor viewport that turns with the camera, so you can always read which way world space is facing. Hovering a tip highlights its axis, and clicking one hands you that axis to snap the view to, like the axis gizmo in Unity or Blender.
Install
dotnet add package BorrowedTorch.SceneGizmo
Targets net10.0-windows. Depends on BorrowedTorch.Camera 2.5.1 or later. It does not bring MonoGame: reference the
MonoGame your game runs on - DesktopGL, WindowsDX or BorrowedTorch's compute fork, any release from 3.8.1.303 on. (1.0.0
brought the old compute fork, MonoGame.Framework.Compute.WindowsDX.NoMemoryLeak, with it.)
Quick start
using BorrowedTorch.SceneGizmo;
using Microsoft.Xna.Framework.Input;
// LoadContent: one gizmo per graphics device. The colors are optional.
_gizmo = new OrientationGizmo(GraphicsDevice)
{
AxisXColor = new Color(220, 70, 70),
AxisYColor = new Color(90, 210, 90),
AxisZColor = new Color(80, 140, 230),
AxisLetterColor = new Color(245, 245, 245)
};
// Update: refresh the hover highlight, and let a click on a tip snap the camera.
var mousePosition = Mouse.GetState().Position;
_gizmo.UpdateHover(_camera, mousePosition);
if (clickedThisFrame && _gizmo.TryPickAxis(_camera, mousePosition, out var axis))
_freeCameraController.SnapTo(-axis); // the clicked axis should point at the viewer, so look down its negative
// Draw: after the scene, so the widget sits on top of it.
_gizmo.Draw(_camera);
// UnloadContent
_gizmo.Dispose();
_camera is a BorrowedTorch.Cameras.Camera. The gizmo reads its View matrix, so it shows the orientation as of
the camera's last Update.
API
| Member | Meaning |
|---|---|
OrientationGizmo(GraphicsDevice) |
Creates the effect and the vertex buffers. Dispose it with the device. |
AxisXColor, AxisYColor, AxisZColor |
Arm and knob colors of the three axes. Negative arms are drawn at 40% brightness. |
AxisLetterColor |
Color of the X / Y / Z letters on the positive tips. |
UpdateHover(camera, mousePosition) |
Sets the hover highlight from the cursor. Call once per frame before Draw, and pass the position even when the cursor is elsewhere: that clears the highlight. |
TryPickAxis(camera, mousePosition, out axis) |
The signed unit axis (Vector3.UnitX, -Vector3.UnitZ, ...) whose tip lies within 14 px of the cursor, or false. The frontmost tip wins when two overlap, and the cursor has to be inside the widget's square. |
Draw(camera) |
Draws the widget in the top-right corner of the current viewport, over whatever is already there. |
Dispose() |
Releases the effect. |
Mouse positions are in pixels of the viewport current at the time of the call, the same GraphicsDevice.Viewport that
Draw places the widget in, so pick with the viewport you draw with.
How it works
- Placement. A 110 px square, 12 px in from the top-right corner of the current viewport. It is drawn through its own viewport with a fixed orthographic projection, so it never scales with the window.
- Orientation. The main camera's view matrix with its translation replaced: the gizmo origin sits 4 units straight ahead and turns exactly as the camera does, wherever the camera is, floating origin included.
- Geometry. Six arms from the origin, built every frame as camera-facing quads in view space. Positive arms are full length and carry a knob and a letter; negative arms are shorter and dimmed. Letters lie in the screen plane, so they stay upright when the camera rolls.
- Order. Depth testing is off so the widget floats above the scene. The quads are sorted far to near on the CPU instead and go to the GPU as a single draw call. Letters are biased slightly toward the viewer so they sit on their own knob, and an arm in front of a letter hides it.
- State. The viewport and the blend, depth-stencil and rasterizer states are saved and restored around the draw. The vertex buffers are reused, so there is no per-frame garbage.
Conventions
MonoGame's right-handed frame: +X right, +Y up, and the camera looks down -Z. The axis TryPickAxis returns is the
world axis of the tip under the cursor, so to look at the scene along it, snap the camera to face its negative.
Building and testing
From the BorrowedTorch.SceneGizmo folder, which holds the solution:
dotnet test
The xUnit suite in BorrowedTorch.SceneGizmo.Tests covers the layout, picking, the quad builder and the painter's sort,
and needs no graphics device.
License
MIT
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0-windows7.0 is compatible. |
-
net10.0-windows7.0
- BorrowedTorch.Camera (>= 2.5.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.