BorrowedTorch.TransformGizmo
1.5.2
Prefix Reserved
dotnet add package BorrowedTorch.TransformGizmo --version 1.5.2
NuGet\Install-Package BorrowedTorch.TransformGizmo -Version 1.5.2
<PackageReference Include="BorrowedTorch.TransformGizmo" Version="1.5.2" />
<PackageVersion Include="BorrowedTorch.TransformGizmo" Version="1.5.2" />
<PackageReference Include="BorrowedTorch.TransformGizmo" />
paket add BorrowedTorch.TransformGizmo --version 1.5.2
#r "nuget: BorrowedTorch.TransformGizmo, 1.5.2"
#:package BorrowedTorch.TransformGizmo@1.5.2
#addin nuget:?package=BorrowedTorch.TransformGizmo&version=1.5.2
#tool nuget:?package=BorrowedTorch.TransformGizmo&version=1.5.2
BorrowedTorch.TransformGizmo
A move / rotate / scale gizmo for MonoGame editors: arms, plane squares, rings and scale boxes held at a fixed share of the screen, picked and dragged with the pointer, over anything that exposes its pose through one small interface. Per-target flags say which modes are offered and whether move and rotate work in world or local space, so one gizmo serves meshes, lights and markers alike.
Install
dotnet add package BorrowedTorch.TransformGizmo
Targets net10.0-windows. Depends on BorrowedTorch.Camera 2.5.1 or later, whose Camera supplies the view, the
pointer ray and the floating-origin offset, perspective or orthographic. 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.1.0 and earlier brought the old
compute fork, MonoGame.Framework.Compute.WindowsDX.NoMemoryLeak, with them.)
Quick start
using BorrowedTorch.TransformGizmos;
// A target adapts whatever is selected. Here, an entity with a pose relative to its parent.
sealed class EntityTarget(Entity entity) : ITransformGizmoTarget
{
public GizmoCapabilities Capabilities => GizmoCapabilities.All;
// Move is handed back in world space; the target carries it through its parents.
public Vector3 WorldPosition
{
get => entity.WorldMatrix.Translation;
set => entity.LocalPosition = Vector3.Transform(value, Matrix.Invert(entity.Parent.WorldMatrix));
}
// The object's own axes as they point in the world: Right, Up and Backward are +X, +Y and +Z of a MonoGame matrix.
public GizmoBasis WorldAxes =>
GizmoBasis.FromObjectAxes(entity.WorldMatrix.Right, entity.WorldMatrix.Up, entity.WorldMatrix.Backward);
// Rotate and scale stay in the object's own space.
public Quaternion LocalRotation { get => entity.LocalRotation; set => entity.LocalRotation = value; }
public Vector3 LocalScale { get => entity.LocalScale; set => entity.LocalScale = value; }
}
var gizmo = new TransformGizmo(GraphicsDevice);
gizmo.TransformMutated += target => inspector.Refresh(); // a drag wrote a new pose
// Update, once per frame, before the scene's own picking. `selected` is null when nothing is selected.
var pixel = new Point(mouse.X, mouse.Y);
var ray = camera.ScreenPointToRay(new Vector2(mouse.X, mouse.Y), GraphicsDevice.Viewport);
gizmo.Update(camera, selected, pixel, mouse.LeftButton == ButtonState.Pressed, ray);
if (leftButtonJustPressed && !gizmo.TryBeginDrag(camera, selected, pixel, ray))
SelectUnderPointer(ray); // the click was not on a handle, so it is the scene's
if (keyJustPressed(Keys.Tab)) gizmo.CycleMode(selected);
if (keyJustPressed(Keys.X)) gizmo.ToggleSpace();
// Draw, last, over the scene:
gizmo.Draw(camera, selected);
Targets
ITransformGizmoTarget is whatever the gizmo is attached to. The gizmo reads the pose from it every frame and, while a
handle is dragged, writes back only the part that handle edits.
| Member | Meaning |
|---|---|
Capabilities |
Which modes, and for move and rotate which frames, the gizmo offers for this target. None hides it. |
RotationAxes |
Which axes rotate turns the target about, a ring for each. Optional: all three unless the target says otherwise. |
WorldPosition |
The pivot in world space: where the gizmo is drawn, and what a move drag sets. |
WorldAxes |
The target's own axes as they point in world space, built with GizmoBasis.FromObjectAxes from the world matrix. A scaled, skewed or mirrored frame is fine: the local handles lie along the real edges. |
LocalRotation |
Rotation relative to the parent: what a rotate drag composes onto and sets. |
LocalScale |
Scale in the target's own frame: what a scale drag multiplies and sets. |
Move works in world space and is handed back as a world position for the implementation to carry through any parents, which is exact at any depth. Rotate and scale work in the target's own space: a rotated child under a non-uniformly scaled parent has a sheared world matrix, and rotation or scale pushed through it would not survive the round trip.
Capabilities
GizmoCapabilities is a flags enum. Any combination is valid: move-only, rotate about the target's own axes only, scale
plus world-space move, and so on.
| Flag | Offers |
|---|---|
TranslateGlobal, TranslateLocal |
Move along, or across the planes of, the world's axes or the target's own. |
RotateGlobal, RotateLocal |
Turn about the world's axes, or about the target's own. |
ScaleAxes |
The three per-axis scale arms, and the plane squares scaling two at once. |
ScaleUniform |
The centre square, scaling all three axes together. |
Translate, Rotate, Scale, All |
The unions. |
A plane square scales two axes and leaves the third, so it comes with ScaleAxes: a target offering ScaleUniform
alone
keeps its proportions.
Scale has no global form: scaling a rotated object along a world axis shears it, and a scale/rotation/translation pose has nowhere to keep shear, so scale is always local.
Rotation axes
RotationAxes narrows rotate to some of its rings: a GizmoAxes flags enum of X, Y and Z (All by default,
through the interface's default member). The axes are those of the frame rotate works in, so a weather vane that may
only turn about the world's up offers RotateGlobal with GizmoAxes.Y, and a door turning on its own hinge
RotateLocal with GizmoAxes.Y. GizmoAxes.None takes rotate away, as if no rotate flag were set.
public GizmoCapabilities Capabilities => GizmoCapabilities.RotateGlobal;
public GizmoAxes RotationAxes => GizmoAxes.Y;
The rules that turn capabilities into what the gizmo does live in GizmoCapabilitiesExtensions, apart from the gizmo
itself so a UI can ask them without a graphics device, to grey out a mode button, say:
| Method | Answer |
|---|---|
Allows(mode), Allows(mode, space) |
Whether a mode is offered at all, or in that frame. |
ResolveSpace(mode, preferred) |
The frame a mode works in: the preferred one when offered there, else the other; scale is always local. |
NextMode(current) |
The next offered mode in translate, rotate, scale order. A lone mode cycles to itself. |
TryClampMode(current, out mode) |
current when offered, else the first offered mode in cycle order; false when nothing is offered. |
WithRotationAxes(axes) |
The capabilities as the gizmo offers them: rotate taken off when axes is None. Ask the rest of it. |
axes.Includes(axis) |
Whether a GizmoAxes set holds the axis X, Y or Z of GizmoAxis. |
Modes and frames
| Mode | Handles |
|---|---|
Translate |
Three arrowed arms and three plane squares. An arm drag slides the pivot along the arm's axis by the pointer's travel along it; a square drag moves it across the square's plane with the pointer. Either way the object stays under the pointer at any depth. |
Rotate |
A ring for each of the target's RotationAxes, three by default. A drag turns the object about the ring's axis by the pointer's angle around it, measured on the ring's own plane. A ring seen edge-on, or a pointer past the plane's horizon, holds the last rotation. |
Scale |
The move arms tipped with boxes, each scaling its own axis by the pointer's travel in arm lengths; the plane squares, scaling both of their axes by the pointer's travel along the square's diagonal; and the centre square, scaling all three by the pointer's travel up-and-right on screen. A drag never takes an axis below 1% of its grab-time scale, so nothing collapses or flips. |
The plane squares sit between each pair of arms, a quarter of the way out, and are named after the axes they span:
GizmoAxis.XY, XZ and YZ. Each takes the colour of the axis it leaves out, so the blue square moves without
touching Z. In a local frame they follow the target's own axes, skewed ones included.
Mode is kept on a mode the current target offers: a Scale left over from a mesh falls back to Translate when a light
is selected. CycleMode(target) steps through the offered modes.
Space is the preferred frame, Global or Local, and ToggleSpace() swaps it. It is a preference: a mode the target
offers in only one frame stays there, and scale is always local, so the swap shows once a mode offered in both frames
is up. Which frame is in use is decided inside Update, TryBeginDrag and Draw from Mode, Space and the target's
capabilities, so callers never have to know the rule.
Mode and space changes mid-drag are ignored, whether through the properties or the methods: the drag's captured state belongs to the mode and frame it was grabbed in.
Skewed and mirrored objects
The local handles follow the object's real axes, which under a non-uniformly scaled parent are not perpendicular. Arms and scale boxes lie along those skewed edges; a ring is measured on a plane square to its own axis, so equal pointer travel is equal rotation all the way round. Where a frame has to stand in for an orientation, carrying a world axis into the object's frame for a global rotate, it is squared up first, which is exact without shear and an approximation with it.
A mirrored object, one with a negative scale, has a left-handed frame. A turn about its local axis moves it the opposite way in the world from an unmirrored object, so the gizmo flips the angle it applies and the object follows the pointer either way.
Interaction
- Hover.
Updatepicks the handle under the pointer, within 9 pixels of an arm's line or a ring, or over a plane square, andDrawhighlights it;IsHoveringsays whether there is one. An arm in reach wins over a square. The pivot square is a handle only in scale mode. - Click or drag.
TryBeginDragstarts a drag when a handle is under the pointer and returns false otherwise, so the click falls through to the scene. A drag stays inert until the pointer has moved 4 pixels from the grab point: a click that never becomes a drag writes nothing, andTransformMutatedfires only when a pose is actually written. - Drag lifetime. A drag ends when the button is released or the target goes away (
Updatewith a null target);EndDragcancels one from outside, andIsDraggingreports it. The axis grabbed is held for the whole drag, so a rotate turns about the ring it started on even as the object, and with it the live local frame, turns underneath. - End-on arms, edge-on squares. An arm shorter than 8 pixels on screen is nearly in line with the view and cannot be picked: a drag along it would be ill-conditioned, flinging the object down the axis. A plane square turned within about 9 degrees of edge-on cannot be picked either, for the same reason, and a square drag whose pointer runs out to the plane's horizon holds the last position rather than chasing it.
- Far from the origin. Geometry and picking are built relative to the camera's floating-origin
Offset, so the gizmo stays crisp wherever the world has got to.
Drawing
Draw renders over everything, with depth testing off and alpha blending on, and restores the blend, depth and
rasterizer states it changed. The gizmo spans 13% of the viewport height at the target's depth along the view, so it is
the same size wherever the target sits on screen - through an orthographic camera, 13% of its view's height, at any
depth (Camera.ViewHeightAt). Its arms, bands and squares face the camera: the eye, or back down the view through an
orthographic camera, whose lines of sight run parallel (Camera.TowardViewer). Where handles overlap they are painted far-to-near, each ring band
segment sorted on its own, so the nearer arc always lands on top; the see-through plane squares go down before the arms.
Colours are AxisXColor, AxisYColor, AxisZColor and CenterColor, the squares taking their axis colours. Dispose
the gizmo with the graphics device; it owns one BasicEffect.
Conventions
MonoGame's right-handed frame: +X right, +Y up, and a camera looks down -Z. A GizmoBasis holds three unit axes that
need not be perpendicular; GizmoBasis.World is the identity frame the global modes use, and FromObjectAxes builds
one from an object's world matrix. Quaternions compose MonoGame-style: a * b applies b, then a.
Building and testing
dotnet test
The solution is BorrowedTorch.TransformGizmo.sln in this folder. The xUnit suite in
../BorrowedTorch.TransformGizmo.Tests
covers the capability rules, the basis maths, the painter's-order sort and the screen projector, 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)
- BorrowedTorch.Math (>= 0.3.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.