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 scale = PixelScale.PerMeter(32);
// Non-metre world: 2 pixels per centimetre
var scale = Length.FromCentimeters(1).ToPixels(2);
// Smooth zoom in a game update loop
_currentScale = PixelScale.Lerp(_currentScale, _targetScale, deltaTime * smoothSpeed);

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 scale = PixelScale.PerMeter(32);
// Non-metre world: 2 pixels per centimetre
var scale = Length.FromCentimeters(1).ToPixels(2);
// Smooth zoom in a game update loop
_currentScale = PixelScale.Lerp(_currentScale, _targetScale, deltaTime * smoothSpeed);

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.

// In a game update loop — smooth zoom toward a target scale
_currentScale = PixelScale.Lerp(_currentScale, _targetScale, deltaTime * smoothSpeed);
camera = camera with { Scale = _currentScale };

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 base = PixelScale.PerMeter(32);
var zoomedIn  = base.ZoomBy(2.0);  // 64 px/m
var zoomedOut = base.ZoomBy(0.5);  // 16 px/m