fract

package
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2026 License: MIT Imports: 3 Imported by: 23

Documentation

Overview

CPU-based vectorial text rendering has always been a performance sensitive task, with glyph rasterization being one of the most critical steps in the process. One of the techniques that can be used to improve the rasterization speed is using fixed point arithmetic instead of floating point arithmetic — and that's what brings us to this subpackage.

The fract subpackage defines a Unit type representing a 26.6 fixed point value and provides numerous methods to perform fixed point operations. Additionally, the subpackage also defines the Point and Rect helper types.

Other font related Golang packages tend to depend on golang.org/x/image/math/fixed instead, but this subpackage offers more methods, more accurate algorithms and is designed to integrate directly with etxt.

Index

Constants

View Source 
const (
	MaxUnit    Unit    = +0x7FFFFFFF
	MinUnit    Unit    = -0x7FFFFFFF - 1
	One        Unit    = 64               // fract.One.ToInt() == 1
	MaxInt     int     = +33554431        // max representable int
	MinInt     int     = -33554432        // min representable int
	MaxFloat64 float64 = +33554431.984375 // max representable float
	MinFloat64 float64 = -33554432        // min representable float
	Delta      float64 = 0.015625         // float equivalent of Unit(1) => 1.0/64.0
	HalfDelta  float64 = 0.0078125        // 1.0/128.0 (used for rounding)
)

Miscellaneous constants related to Unit.

Variables

This section is empty.

Functions

This section is empty.

Types

type Point 

type Point struct {
	X Unit
	Y Unit
}

A pair of Unit coordinates. Commonly used during rendering processes to keep track of the pen position within the rendering target.

func IntsToPoint 

func IntsToPoint(x, y int) Point

Creates a point from a pair of ints.

func UnitsToPoint 

func UnitsToPoint(x, y Unit) Point

Creates a point from a pair of units.

func (Point) AddPoint 

func (self Point) AddPoint(point Point) Point

Returns the result of adding the two points.

func (Point) AddUnits 

func (self Point) AddUnits(x, y Unit) Point

Returns the result of adding the given pair of units to the current point coordinates.

func (Point) Floor added in v0.0.10 

func (self Point) Floor() Point

Returns the floor of the point coordinates.

func (Point) ImagePoint 

func (self Point) ImagePoint() image.Point

Converts the point coordinates to ints and returns them as an image.Point stdlib value. The conversion will round the units if necessary, which could be problematic in some contexts.

func (Point) In 

func (self Point) In(rect Rect) bool

Returns whether the current point is inside the given Rect.

func (Point) String 

func (self Point) String() string

Returns a textual representation of the point (e.g.: "(2.5, -4)").

func (Point) ToFloat32s 

func (self Point) ToFloat32s() (x, y float32)

Returns the point coordinates as a pair of float32s.

func (Point) ToFloat64s 

func (self Point) ToFloat64s() (x, y float64)

Returns the point coordinates as a pair of float64s.

func (Point) ToInts 

func (self Point) ToInts() (int, int)

Returns the point coordinates as a pair of ints. The conversion will round the units if necessary, which could be problematic in some contexts.

type Rect 

type Rect struct {
	Min Point
	Max Point
}

A pair of Point values defining a rectangular region. Like image.Rectangle, the Max point is not included in the rectangle. The behavior for malformed rectangles is undefined.

func FromImageRect 

func FromImageRect(rect image.Rectangle) Rect

Creates a rect from an image.Rectangle.

func IntsToRect 

func IntsToRect(minX, minY, maxX, maxY int) Rect

Creates a rect from a set of four integers.

func PointsToRect 

func PointsToRect(min, max Point) Rect

Creates a rect from a pair of points.

func UnitsToRect 

func UnitsToRect(minX, minY, maxX, maxY Unit) Rect

Creates a rect from a set of four units.

func (Rect) AddImagePoint 

func (self Rect) AddImagePoint(point image.Point) Rect

Returns the result of translating the rect by the given value.

func (Rect) AddInts 

func (self Rect) AddInts(x, y int) Rect

Returns the result of translating the rect by the given values.

func (Rect) AddPoint 

func (self Rect) AddPoint(pt Point) Rect

Returns the result of translating the rect by the given value.

func (Rect) AddUnits 

func (self Rect) AddUnits(x, y Unit) Rect

Returns the result of translating the rect by the given values.

func (Rect) CenteredAtIntCoords 

func (self Rect) CenteredAtIntCoords(x, y int) Rect

Returns the result of translating the rect so its center becomes aligned to the given coordinates.

func (Rect) Clip 

func (self Rect) Clip(image *ebiten.Image) *ebiten.Image

Utility function to retrieve the subimage corresponding to the rect area.

func (Rect) Contains 

func (self Rect) Contains(point Point) bool

Returns whether the rect contains the given point or not.

Remember that point == Rect.Min is included, but point == Rect.Max is not.

func (Rect) Empty 

func (self Rect) Empty() bool

Returns whether the rect is empty or not.

func (Rect) HasZeroOrigin 

func (self Rect) HasZeroOrigin() bool

Returns whether the Min point is (0, 0) or not.

func (Rect) Height 

func (self Rect) Height() Unit

Returns the height of the rect.

func (Rect) ImageRect 

func (self Rect) ImageRect() image.Rectangle

Converts the rect coordinates to ints and returns them as an image.Rectangle stdlib value. The conversion will round the units if necessary, which could be problematic in some contexts.

func (Rect) IntHeight 

func (self Rect) IntHeight() int

Returns the height of the rect as an int. The conversion may introduce a loss of precision, but the returned int height is guaranteed to be >= than the original.

func (Rect) IntOrigin 

func (self Rect) IntOrigin() (int, int)

Returns the Min point as a pair of ints. The conversion may introduce a loss of precision, but the returned coordinates are guaranteed to be <= than the original.

func (Rect) IntSize 

func (self Rect) IntSize() (width, height int)

Utility method equivalent to (Rect.IntWidth(), Rect.IntHeight()).

func (Rect) IntWidth 

func (self Rect) IntWidth() int

Returns the width of the rect as an int. The conversion may introduce a loss of precision, but the returned int width is guaranteed to be >= than the original.

func (Rect) PadInts 

func (self Rect) PadInts(horzMargin, vertMargin int) Rect

Same as Rect.PadUnits() but with ints.

func (Rect) PadUnits 

func (self Rect) PadUnits(horzPad, vertPad Unit) Rect

Returns the result of applying the given paddings to each side of the rect. In other words, the rect's width after the padding is increased by horzPad*2 (likewise for the height with vertPad*2).

func (Rect) Size 

func (self Rect) Size() (width, height Unit)

Utility method equivalent to (Rect.Width(), Rect.Height()).

func (Rect) String 

func (self Rect) String() string

Returns a textual representation of the rect (e.g.: "(0, 0) - (1.5, 8.5)").

func (Rect) ToFloat32s 

func (self Rect) ToFloat32s() (minX, minY, maxX, maxY float32)

Returns the rect coordinates as a set of four float32s.

func (Rect) ToFloat64s 

func (self Rect) ToFloat64s() (minX, minY, maxX, maxY float64)

Returns the rect coordinates as a set of four float64s.

func (Rect) ToInts 

func (self Rect) ToInts() (minX, minY, maxX, maxY int)

Returns the rect coordinates as a set of four ints. The conversion may introduce a loss of precision, but the returned ints are guaranteed to contain the original rect.

func (Rect) Width 

func (self Rect) Width() Unit

Returns the width of the rect.

type Unit 

type Unit int32

Fixed point type to represent fractional values used for font rendering.

26 bits represent the integer part of the value, while the remaining 6 bits represent the decimal part. For an intuitive understanding, if you know that var ms Millis = 1000 is storing the equivalent to 1 second, then with Unit instead of 1/1000ths of a value you are storing 1/64ths. For example: var pixels Unit = 64 would represent 1 pixel; 96 would be equivalent to 1.5 instead.

The internal representation is compatible with fixed.Int26_6.

func FromFloat64 

func FromFloat64(value float64) Unit

Converts a float64 to the closest Unit, rounding away from zero in case of ties. Doesn't account for NaNs, infinites nor overflows. See also FromFloat64Up() and FromFloat64Down().

func FromFloat64Down 

func FromFloat64Down(value float64) Unit

Converts a float64 to the closest Unit, rounding down in case of ties. Doesn't account for NaNs, infinites nor overflows.

func FromFloat64Up 

func FromFloat64Up(value float64) Unit

Converts a float64 to the closest Unit, rounding up in case of ties. Doesn't account for NaNs, infinites nor overflows.

func FromInt 

func FromInt(value int) Unit

Fast conversion from int to Unit. If the int value is not representable with a Unit, the result is undefined. If you want to account for overflows, check MinInt <= value <= MaxInt.

func (Unit) Abs 

func (self Unit) Abs() Unit

Returns the absolute value of the unit.

func (Unit) Away 

func (self Unit) Away(reference int) Unit

Returns the closest whole value in the direction opposite to the refence parameter.

func (Unit) Ceil 

func (self Unit) Ceil() Unit

Returns the ceil value of the unit.

func (Unit) Div 

func (self Unit) Div(divisor Unit) Unit

Returns the result of dividing the unit by the given divisor, rounding the unrepresentable decimals away from zero in case of ties.

func (Unit) Floor 

func (self Unit) Floor() Unit

Returns the floor value of the unit.

func (Unit) Fract 

func (self Unit) Fract() Unit

Returns only the fractional part of the unit.

func (Unit) FractShift 

func (self Unit) FractShift() Unit

Returns the fractional distance to self.Floor() (the distance to the nearest smaller or equal integer).

This is commonly used for glyph position quantization.

func (Unit) HalfAway 

func (self Unit) HalfAway(reference int) Unit

Returns the result of rounding the unit away from the given reference parameter.

func (Unit) HalfDown 

func (self Unit) HalfDown() Unit

Returns the result of rounding down the unit.

func (Unit) HalfToward 

func (self Unit) HalfToward(reference int) Unit

Returns the result of rounding the unit towards the given reference parameter.

func (Unit) HalfUp 

func (self Unit) HalfUp() Unit

Returns the result of rounding up the unit.

func (Unit) IsWhole 

func (self Unit) IsWhole() bool

Returns true if the current value is a whole number, or false if the fractional part is non-zero.

func (Unit) Mul 

func (self Unit) Mul(multiplier Unit) Unit

Returns the result of multiplying the unit by the given value, rounding the unrepresentable decimals away from zero in case of ties.

func (Unit) MulDown 

func (self Unit) MulDown(multiplier Unit) Unit

Returns the result of multiplying the unit by the given value, rounding the unrepresentable decimals down in case of ties.

func (Unit) MulInt 

func (self Unit) MulInt(multiplier int) Unit

Returns the result of multiplying the unit by the given int.

func (Unit) MulUp 

func (self Unit) MulUp(multiplier Unit) Unit

Returns the result of multiplying the unit by the given value, rounding the unrepresentable decimals up in case of ties.

func (Unit) QuantizeDown 

func (self Unit) QuantizeDown(step Unit) Unit

Given a fractional step between 1 and 64, it quantizes the unit to that fractional value and returns it, favoring the lower value in case of ties.

func (Unit) QuantizeUp 

func (self Unit) QuantizeUp(step Unit) Unit

Given a fractional step between 1 and 64, it quantizes the unit to that fractional value and returns it, favoring the higher value in case of ties.

func (Unit) Rescale 

func (self Unit) Rescale(from, to Unit) Unit

Returns the result of rescaling the unit from the 'from' scale to the 'to' scale, rounding the unrepresentable decimals away from zero in case of ties.

Within etxt, this is often used to rescale font metrics between different EM sizes (e.g. an advance of 512 on a font with EM of 1024 units corresponds to an advance of 384 with an EM size of 768, or 512.Rescale(1024, 768) = 384).

Notice that there's an implicit division in this operation; if 'from' is zero, the function will panic.

func (Unit) ToFloat32 

func (self Unit) ToFloat32() float32

Returns the unit as a float32. The conversion is exact in the +/-16777216 units range. Beyond that range, which corresponds to +/-2^18 (+/-262144) in the decimal numbering system, conversions become progressively less precise.

func (Unit) ToFloat64 

func (self Unit) ToFloat64() float64

Returns the unit as a float64. The conversion is always exact.

func (Unit) ToInt 

func (self Unit) ToInt() int

Utility method equivalent to Unit.ToIntHalfAway(0). For the fastest possible conversion to int, check Unit.ToIntFloor() instead.

func (Unit) ToIntAway 

func (self Unit) ToIntAway(reference int) int

Returns the closest int to the unit in the direction opposite to the reference parameter.

func (Unit) ToIntCeil 

func (self Unit) ToIntCeil() int

Returns the integer ceil of the unit.

func (Unit) ToIntFloor 

func (self Unit) ToIntFloor() int

Returns the unit as a truncated int. This is the fastest Unit to int conversion method.

func (Unit) ToIntHalfAway 

func (self Unit) ToIntHalfAway(reference int) int

Rounds the unit away from the reference value and returns the result as an int.

func (Unit) ToIntHalfDown 

func (self Unit) ToIntHalfDown() int

Returns the unit as a rounded down int.

func (Unit) ToIntHalfToward 

func (self Unit) ToIntHalfToward(reference int) int

Rounds the unit towards the reference value and returns the result as an int.

func (Unit) ToIntHalfUp 

func (self Unit) ToIntHalfUp() int

Returns the unit as a rounded up int.

func (Unit) ToIntToward 

func (self Unit) ToIntToward(reference int) int

Returns the closest int to the unit in the direction given by the reference parameter.

func (Unit) Toward 

func (self Unit) Toward(reference int) Unit

Returns the closest whole value in the direction given by the refence parameter.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.