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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BorrowedTorch.TransformGizmo" Version="1.5.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BorrowedTorch.TransformGizmo" Version="1.5.2" />
                    
Directory.Packages.props
<PackageReference Include="BorrowedTorch.TransformGizmo" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BorrowedTorch.TransformGizmo --version 1.5.2
                    
#r "nuget: BorrowedTorch.TransformGizmo, 1.5.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BorrowedTorch.TransformGizmo@1.5.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BorrowedTorch.TransformGizmo&version=1.5.2
                    
Install as a Cake Addin
#tool nuget:?package=BorrowedTorch.TransformGizmo&version=1.5.2
                    
Install as a Cake Tool

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. Update picks the handle under the pointer, within 9 pixels of an arm's line or a ring, or over a plane square, and Draw highlights it; IsHovering says 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. TryBeginDrag starts 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, and TransformMutated fires only when a pose is actually written.
  • Drag lifetime. A drag ends when the button is released or the target goes away (Update with a null target); EndDrag cancels one from outside, and IsDragging reports 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 Compatible and additional computed target framework versions.
.NET net10.0-windows7.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.5.2 86 11/18/2026
1.5.1 80 11/18/2026
1.5.0 84 11/18/2026
1.4.0 87 11/17/2026
1.3.0 93 11/16/2026
1.2.0 100 11/14/2026
1.1.0 117 10/29/2026
1.0.1 128 10/16/2026
1.0.0 113 10/16/2026