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

Lerp(PixelScale, PixelScale, double)

Linearly interpolates between two PixelScale values.

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);

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);

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