Struct PixelScale

Namespace

Thunder.UnitsNET.Vectors.MonoGame

Assembly

Thunder.UnitsNET.Vectors.MonoGame.dll

Defines the relationship between world-space length and screen-space pixels, encoding both the scale factor and the world unit together.

public readonly record struct PixelScale : IEquatable<PixelScale>

Implements

IEquatable<PixelScale>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

A PixelScale answers the question: "how many pixels does one world unit occupy on screen?" For example, PixelScale.PerMeter(32) means one metre in world space occupies 32 pixels on screen.

Changing the PixelScale of a Camera2 is how zoom is implemented. More pixels per unit means the world appears larger (zoomed in); fewer pixels per unit means the world appears smaller (zoomed out).

// Common case: 32 pixels per metre
var metreScale = PixelScale.PerMeter(32);
// Non-metre world: 2 pixels per centimetre
var cmScale = Length.FromCentimeters(1).ToPixels(2);
// Smooth zoom in a game update loop
var currentScale = PixelScale.PerMeter(32);
var targetScale  = PixelScale.PerMeter(64);
currentScale = PixelScale.Lerp(currentScale, targetScale, 0.016 * 5.0);

Constructors

PixelScale(Length, double)

Defines the relationship between world-space length and screen-space pixels, encoding both the scale factor and the world unit together.

public PixelScale(Length WorldLength, double Pixels)

Parameters

WorldLength Length

The world-space length that corresponds to Pixels pixels. Its unit determines Unit.

Pixels double

The number of screen pixels that WorldLength occupies.

Remarks

A PixelScale answers the question: "how many pixels does one world unit occupy on screen?" For example, PixelScale.PerMeter(32) means one metre in world space occupies 32 pixels on screen.

Changing the PixelScale of a Camera2 is how zoom is implemented. More pixels per unit means the world appears larger (zoomed in); fewer pixels per unit means the world appears smaller (zoomed out).

// Common case: 32 pixels per metre
var metreScale = PixelScale.PerMeter(32);
// Non-metre world: 2 pixels per centimetre
var cmScale = Length.FromCentimeters(1).ToPixels(2);
// Smooth zoom in a game update loop
var currentScale = PixelScale.PerMeter(32);
var targetScale  = PixelScale.PerMeter(64);
currentScale = PixelScale.Lerp(currentScale, targetScale, 0.016 * 5.0);

Properties

Pixels

The number of screen pixels that WorldLength occupies.

public double Pixels { get; init; }

Property Value

double

PixelsPerUnit

The number of pixels per one Unit in world space. For example, 32.0 means one Unit occupies 32 pixels.

public double PixelsPerUnit { get; }

Property Value

double

Unit

The world-space UnitsNet.Units.LengthUnit that PixelsPerUnit is measured in. Determined by the unit of WorldLength.

public LengthUnit Unit { get; }

Property Value

LengthUnit

WorldLength

The world-space length that corresponds to Pixels pixels. Its unit determines Unit.

public Length WorldLength { get; init; }

Property Value

Length

Methods

Clamp(double, double)

Returns a new PixelScale with PixelsPerUnit clamped to [minPixelsPerUnit, maxPixelsPerUnit]. WorldLength and Unit are unchanged.

public PixelScale Clamp(double minPixelsPerUnit, double maxPixelsPerUnit)

Parameters

minPixelsPerUnit double

The minimum allowed pixels per world unit.

maxPixelsPerUnit double

The maximum allowed pixels per world unit.

Returns

PixelScale

The same PixelScale if already within range; otherwise a new instance with PixelsPerUnit set to the nearest bound.

Examples

var scale = PixelScale.PerMeter(128);
var clamped = scale.Clamp(16, 64); // ≈ 64 px/m

Remarks

Use Clamp(double, double) to enforce zoom limits on a Camera2. For a camera-level convenience, see Camera2.ClampZoom.

Clamp(PixelScale, PixelScale)

Returns a new PixelScale with PixelsPerUnit clamped to [min, max], where both bounds are expressed as PixelScale values and normalised to the receiver's Unit before comparison. WorldLength and Unit are unchanged.

public PixelScale Clamp(PixelScale min, PixelScale max)

Parameters

min PixelScale

The minimum zoom level. Normalised to the receiver's unit for comparison.

max PixelScale

The maximum zoom level. Normalised to the receiver's unit for comparison.

Returns

PixelScale

The same PixelScale if already within range; otherwise a new instance clamped to the nearest bound.

Examples

var scale   = PixelScale.PerMeter(128);
var clamped = scale.Clamp(PixelScale.PerMeter(16), PixelScale.PerMeter(64)); // ≈ 64 px/m

Remarks

Use the typed overload when bounds come from game configuration expressed as full PixelScale values (e.g. PixelScale.PerMeter(16)). For raw pixel-per-unit doubles, use Clamp(Double, Double).

Lerp(PixelScale, PixelScale, double)

public static PixelScale Lerp(PixelScale a, PixelScale b, double t)

Parameters

a PixelScale

The start scale, returned when t is 0.

b PixelScale

The end scale, returned when t is 1.

t double

The interpolation factor. 0 returns a; 1 returns b; values in between return a proportional blend.

Returns

PixelScale

A new PixelScale whose PixelsPerUnit is linearly interpolated between a and b. The result Unit matches a's unit. If a and b use different units, b is normalised to a's unit before interpolating.

Remarks

Calling Lerp(PixelScale, PixelScale, double) every frame with a small t produces smooth, asymptotic zoom — fast at first, slowing as the scale approaches the target.

// Smooth zoom toward a target scale — call each update frame:
var currentScale = PixelScale.PerMeter(32);
var targetScale  = PixelScale.PerMeter(64);
currentScale = PixelScale.Lerp(currentScale, targetScale, 0.016 * 5.0);

Lerp(PixelScale, PixelScale, Ratio)

Linearly interpolates between two PixelScale values using a typed UnitsNet.Ratio interpolation parameter.

public static PixelScale Lerp(PixelScale a, PixelScale b, Ratio t)

Parameters

a PixelScale

The start scale, returned when t is zero.

b PixelScale

The end scale, returned when t is one.

t Ratio

The interpolation factor as a UnitsNet.Ratio. A decimal-fraction value of 0 returns a; 1 returns b.

Returns

PixelScale

A new PixelScale whose PixelsPerUnit is linearly interpolated between a and b.

Examples

var currentScale = PixelScale.PerMeter(32);
var targetScale  = PixelScale.PerMeter(64);
currentScale = PixelScale.Lerp(currentScale, targetScale, Ratio.FromDecimalFractions(0.5));

PerMeter(double)

Creates a PixelScale where one metre in world space occupies pixels pixels on screen.

public static PixelScale PerMeter(double pixels)

Parameters

pixels double

The number of pixels per metre.

Returns

PixelScale

A PixelScale with Unit set to metres.

Examples

// 32 pixels represent one metre in world space
var scale = PixelScale.PerMeter(32);

PerUnit(LengthUnit, double)

Creates a PixelScale where one unit in world space occupies pixels pixels on screen.

public static PixelScale PerUnit(LengthUnit unit, double pixels)

Parameters

unit LengthUnit

The world-space length unit.

pixels double

The number of pixels per one unit.

Returns

PixelScale

A PixelScale with Unit set to unit.

Examples

// 2 pixels represent one centimetre in world space
var cmScale = PixelScale.PerUnit(LengthUnit.Centimeter, 2);

Remarks

Use PerMeter(double) for the common metre case. Use PerUnit when the world coordinate system is defined in a different unit (e.g. centimetres or tiles).

ZoomBy(double)

Returns a new PixelScale with the pixel density multiplied by factor. The WorldLength and Unit are unchanged.

public PixelScale ZoomBy(double factor)

Parameters

factor double

The zoom multiplier. Values greater than 1.0 zoom in (more pixels per unit); values between 0 and 1.0 zoom out (fewer pixels per unit).

Returns

PixelScale

A new PixelScale with the adjusted pixel density.

Examples

var original  = PixelScale.PerMeter(32);
var zoomedIn  = original.ZoomBy(2.0);  // 64 px/m
var zoomedOut = original.ZoomBy(0.5);  // 16 px/m