video#

This module provides access to the entire GBA video hardware: registers, VRAM, PAL RAM and OAM.

I/O Registers#

Display Control#

type DisplayMode = enum#

type DisplayLayer = enum#

type DisplayLayers = set[DisplayLayer]#

type DispCnt = object#

func gb(dcnt: DispCnt): bool#: True if cartridge is a GBC game. Read-only.

func layers(dcnt: DispCnt): DisplayLayers#: Get the currently enabled display layers as a bit-set.

var dispcnt: DispCnt#: Display control register

const allDisplayLayers = { lBg0, lBg1, lBg2, lBg3, lObj }#

Display Status#

type DispStat = object#

func inVBlank(dstat: DispStat): bool#: VBlank status, read only. True during VBlank, false during VDraw.

func inHBlank(dstat: DispStat): bool#: HBlank status, read only. True during HBlank.

func inVCountTrigger(dstat: DispStat): bool#: VCount trigger status. True if the current scanline matches the scanline trigger (vcount == dispstat.vcountTrigger)

var dispstat: DispStat#: Display status register

let vcount: uint16#: Scanline count (read only)

BG Control#

type BgSize = distinct uint16#

type RegBgSize = enum#: Size of a regular background in tiles. Implicitly convertible to type BgSize.

type AffBgSize = enum#: Size of an affine background in tiles. Implicitly convertible to type BgSize.

type BgCnt = object#: Background control register value.

converter toBgSize(r: RegBgSize): BgSize#

converter toBgSize(a: AffBgSize): BgSize#

BG Scrolling#

type Point16 = object#

type BgPoint = Point16#

var bgcnt: array[4, BgCnt]#: BG control registers

var bgofs: array[4, BgOfs]#: [Write only!] BG scroll registers

BG Affine Transformations#

var bgaff: array[2..3, BgAffine]#: [Write only!] Affine parameters (matrix and scroll offset) for BG2 and BG3, depending on display mode.

type BgAffine = AffDstEx#: Affine parameters for backgrounds; range : 0400:0020 - 0400:003F

type BgAffineSource = AffSrcEx#

type BgAffineDest = AffDstEx#

proc setTo(bgaff: var BgAffine, pa, pb, pc, pd: Fixed)#: Set the elements of a bg affine matrix.

proc setToIdentity(bgaff: var BgAffine)#: Set an bg affine matrix to the identity matrix

proc setToScale(bgaff: var BgAffine, sx, sy: Fixed)#: Set an bg affine matrix for scaling.

proc setToShearX(bgaff: var BgAffine, hx: Fixed)#

proc setToShearY(bgaff: var BgAffine, hy: Fixed)#

proc setToRotation(bgaff: var BgAffine, alpha: uint16)#

Set bg matrix to counter-clockwise rotation.

Bgaff:: BG affine struct to set.
Alpha:: CCW angle. full-circle is 0x10000.

proc setToScaleAndRotation(bgaff: var BgAffine, sx, sy: Fixed, alpha: uint16)#

Set bg matrix to 2d scaling, then counter-clockwise rotation.

Bgaff:: BG affine struct to set.
Sx:: Horizontal scale (zoom). 24.8 fixed point.
Sy:: Vertical scale (zoom). 24.8 fixed point.
Alpha:: CCW angle. full-circle is 0x10000.

proc setToScaleAndRotation(bgaff: var BgAffine, sx, sy: Fixed, alpha: uint16)#

Set bg matrix to 2d scaling, then counter-clockwise rotation.

Bgaff:: BG affine struct to set.
Sx:: Horizontal scale (zoom). 24.8 fixed point.
Sy:: Vertical scale (zoom). 24.8 fixed point.
Alpha:: CCW angle. full-circle is 0x10000.

proc premul(dst: var BgAffine, src: ptr BgAffine)#

Pre-multiply the matrix dst by src

i.e. dst = src * dst

Warning

Don’t use this on bgaff registers, as they are write-only.

proc postmul(dst: var BgAffine, src: ptr BgAffine)#

Post-multiply the matrix dst by src

i.e. dst = dst * src

Warning

Don’t use this on bgaff registers, as they are write-only.

proc rotscaleEx(bgaff: var BgAffine, asx: ptr AffSrcEx)#

Set bg affine matrix to a rot/scale around an arbitrary point.

Bgaff:: BG affine data to set.
Asx:: Affine source data: screen and texture origins, scales and angle.

Windowing#

type WinH = object#: Defines the horizontal bounds of a window (left ..< right)

type WinV = object#: Defines the vertical bounds of a window (top ..< bottom)

type WindowLayer = enum#

type WinCnt = set[WindowLayer]#: Allows to make changes to one half of a window control register.

const allWindowLayers = { wlBg0, wlBg1, wlBg2, wlBg3, wlObj, wlBlend }#

var winh: array[2, WinH]#: [Write only!] Sets the left and right bounds of a window

var winv: array[2, WinV]#: [Write only!] Sets the upper and lower bounds of a window

var win0h: WinH#: [Write only!] Sets the left and right bounds of window 0

var win1h: WinH#: [Write only!] Sets the left and right bounds of window 1

var win0v: WinV#: [Write only!] Sets the upper and lower bounds of window 0

var win1v: WinV#: [Write only!] Sets the upper and lower bounds of window 1

var win0cnt: WinCnt#: Window 0 control

var win1cnt: WinCnt#: Window 1 control

var winoutcnt: WinCnt#: Out window control

var winobjcnt: WinCnt#: Object window control

proc setWindow(winId: range[0..1], bounds: Rect)#

Apply a rectangular window to one of the window registers.

The rectangle is clamped to the bounds of the screen.

Mosaic#

var mosaic: Mosaic#: [Write only!] Mosaic size register

Blending#

type BldCnt = distinct uint16#: Blend control register

type BlendMode = enum#: Color special effects modes

type BlendLayer = enum#

type BlendLayers = set[BlendLayer]#

const allBlendLayers = { blBg0, blBg1, blBg2, blBg3, blObj, blBd }#

proc `a=`(bld: var BldCnt, layers: BlendLayers)#

proc a(bld: BldCnt): BlendLayers#: Upper layer of color special effects.

proc `b=`(bld: var BldCnt, layers: BlendLayers)#

proc b(bld: BldCnt): BlendLayers#: Lower layer of color special effects.

proc mode(bld: BldCnt): BlendMode#: Color special effects mode

proc `mode=`(bld: var BldCnt, v: BlendMode)#

type BlendCoefficient = uint16#: A blend value ranging from 0..16. Values from 17..31 are treated the same as 16.

type BlendAlpha = distinct uint16#: Alpha blending levels. Features two coefficients: eva for the top layer, evb for the bottom layer.

type BlendBrightness = distinct uint16#: Brightness level (fade to black or white). Has a single coefficient evy.

proc `eva=`(bldalpha: var BlendAlpha, v: BlendCoefficient)#

proc eva(bldalpha: BlendAlpha): BlendCoefficient#: Upper layer alpha blending coefficient

proc `evb=`(bldalpha: var BlendAlpha, v: BlendCoefficient)#

proc evb(bldalpha: BlendAlpha): BlendCoefficient#: Lower layer alpha blending coefficient

proc `evy=`(bldy: var BlendBrightness, v: BlendCoefficient)#: Brightness coefficient (write-only!)

var bldcnt: BldCnt#: Blend control register

var bldalpha: BlendAlpha#: Alpha blending fade coefficients

var bldy: BlendBrightness#: [Write only!] Brightness (fade in/out) coefficient

General#

proc clear[T: Screenblock | Charblock | Charblock8 | Tile | Tile8 | M3Mem | M4Mem | M5Mem](dst: var T)#: Clear a region of VRAM (i.e. map, tiles or framebuffer).

Colors#

Types#

type Color = distinct uint16#: A 15bpp colour value. (xbbbbbgggggrrrrr format)

type Palette = array[16, Color]#: A 16-color palette

Accessors#

func `r=`(color: var Color, r: int)#

func r(color: Color): int#: Get the red component of a 15-bit color.

func `g=`(color: var Color, g: int)#

func g(color: Color): int#: Get the green component of a 15-bit color.

func `b=`(color: var Color, b: int)#

func b(color: Color): int#: Get the blue component of a 15-bit color.

proc rgb5(red, green, blue: int): Color#: Create a 15-bit BGR color.

proc rgb5safe(red, green, blue: int): Color#: Create a 15-bit BGR color, with proper masking of R,G,B components.

proc rgb8(red, green, blue: uint8): Color#: Create a 15-bit BGR color, using 8-bit components

proc rgb8(rgb: int): Color#: Create a 15-bit BGR color from a 24-bit RGB color of the form 0xRRGGBB

Color memory#

var bgColorMem: array[256, Color]#

Access to BG PAL RAM as a single array of colors.

This is useful when working with 8bpp backgrounds, or display mode 4.

var bgPalMem: array[16, Palette]#

Access to BG PAL RAM as a table of 16-color palettes.

This is useful when working when 4bpp backgrounds.

Example:

# set all colors of the first palette in memory to white.
for color in bgPalMem[0].mitems:
  color = clrWhite

var objColorMem: array[256, Color]#

Access to OBJ PAL RAM as a single array of colors.

This is useful when working with 8bpp sprites.

var objPalMem: array[16, Palette]#

Access to OBJ PAL RAM as a table of 16-color palettes.

This is useful when working when 4bpp sprites.

Color Constants#

const clrBlack = 0x0000.Color#

const clrRed = 0x001F.Color#

const clrLime = 0x03E0.Color#

const clrYellow = 0x03FF.Color#

const clrBlue = 0x7C00.Color#

const clrMagenta = 0x7C1F.Color#

const clrCyan = 0x7FE0.Color#

const clrWhite = 0x7FFF.Color#

const clrDead = 0xDEAD.Color#

const clrMaroon = 0x0010.Color#

const clrGreen = 0x0200.Color#

const clrOlive = 0x0210.Color#

const clrOrange = 0x021F.Color#

const clrNavy = 0x4000.Color#

const clrPurple = 0x4010.Color#

const clrTeal = 0x4200.Color#

const clrGray = 0x4210.Color#

const clrMedGray = 0x5294.Color#

const clrSilver = 0x6318.Color#

const clrMoneyGreen = 0x6378.Color#

const clrFuchsia = 0x7C1F.Color#

const clrSkyBlue = 0x7B34.Color#

const clrCream = 0x7BFF.Color#

Bulk color manipulation#

These functions are lifted straight from libtonc.

They’re unsafe as they deal with raw pointers.

proc clrRotate(clrs: ptr Color, nclrs: int, ror: int)#: Rotate nclrs colors at clrs to the right by ror.

proc clrBlend(srca: ptr Color, srcb: ptr Color, dst: ptr Color, nclrs: int, alpha: int)#

Blends color arrays srca and srcb into dst. Specific transitional blending effects can be created by making a ‘target’ color array with other routines, then using alpha to morph into it.

Srca:: Source array A.
Srcb:: Source array B.
Dst:: Destination array.
Nclrs:: Number of colors.
Alpha:: Blend weight (range: 0-32). 0 Means full srca

proc clrFade(src: ptr Color, clr: Color, dst: ptr Color, nclrs: int, alpha: int)#

Fades color arrays srca to clr into dst.

Src:: Source array.
Clr:: Final color (at alpha=32).
Dst:: Destination array.
Nclrs:: Number of colors.
Alpha:: Blend weight (range: 0-32). 0 Means full srca

proc clrGrayscale(dst: ptr Color, src: ptr Color, nclrs: int)#

Transform colors to grayscale.

Dst:: Destination color array
Src:: Source color array.
Nclrs:: Number of colors.

proc clrRgbscale(dst: ptr Color, src: ptr Color, nclrs: int, clr: Color)#

Transform colors to an rgb-scale. .. note:

`clr` indicates a color vector in RGB-space. Each source color is converted to a brightness value (i.e. grayscale)
and then mapped onto that color vector. A grayscale is a special case of this, using a color with R=G=B.

Dst:: Destination color array
Src:: Source color array.
Nclrs:: Number of colors.
Clr:: Destination color vector.

proc clrAdjBrightness(dst: ptr Color, src: ptr Color, nclrs: int, bright: Fixed)#

Adjust brightness by bright Operation: color= color+dB;

Dst:: Destination color array
Src:: Source color array.
Nclrs:: Number of colors.
Bright:: Brightness difference, dB (in 24.8f)

proc clrAdjContrast(dst: ptr Color, src: ptr Color, nclrs: int, contrast: Fixed)#

Adjust contrast by contrast Operation: color = color*(1+dC) - MAX*dC/2

Dst:: Destination color array
Src:: Source color array.
Nclrs:: Number of colors.
Contrast:: Contrast difference, dC (in 24.8f)

proc clrAdjIntensity(dst: ptr Color, src: ptr Color, nclrs: int, intensity: Fixed)#

Adjust intensity by intensity. Operation: color = (1+dI)*color.

Dst:: Destination color array
Src:: Source color array.
Nclrs:: Number of colors.
Intensity:: Intensity difference, dI (in 24.8f)

proc palGradient(pal: ptr Color, first: int, last: int)#

Create a gradient between pal[first] and pal[last].

Pal:: Palette to work on.
First:: First index of gradient.
Last:: Last index of gradient.

proc palGradient(pal: ptr Color, first, last: int, clrFirst, clrLast: Color)#

Create a gradient between pal[first] and pal[last].

Pal:: Palette to work on.
First:: First index of gradient.
Last:: Last index of gradient.
ClrFirst:: Color of first index.
ClrLast:: Color of last index.

proc clrBlendFast(srca: ptr Color, srcb: ptr Color, dst: ptr Color, nclrs: int, alpha: int)#

Blends color arrays srca and srcb into dst.

Srca:: Source array A.
Srcb:: Source array B.
Dst:: Destination array.
Nclrs:: Number of colors.
Alpha:: Blend weight (range: 0-32).

Note

This is an ARM assembly routine placed in IWRAM, which makes it very fast, but keep in mind that IWRAM is a limited resource.

proc clrFadeFast(src: ptr Color, clr: Color, dst: ptr Color, nclrs: int, alpha: int)#

Fades color arrays srca to clr into dst.

Src:: Source array.
Clr:: Final color (at alpha=32).
Dst:: Destination array.
Nclrs:: Number of colors.
Alpha:: Blend weight (range: 0-32).

Note

This is an ARM assembly routine placed in IWRAM, which makes it very fast, but keep in mind that IWRAM is a limited resource.

Tiled backgrounds#

proc bgIsAffine(n: int): bool#

proc bgIsAvailable(n: int): bool#

Tile data#

type Tile = Tile4#

type Tile4 = object#: 4bpp tile type, for easy indexing and copying of 16-color tiles

type Tile8 = object#: 8bpp tile type, for easy indexing and copying of 256-color tiles

type Charblock = array[512, Tile]#

type Charblock8 = array[256, Tile8]#

type UnboundedCharblock = distinct array[512, Tile]#

type UnboundedCharblock8 = distinct array[256, Tile8]#

var bgTileMem: array[4, UnboundedCharblock]#

BG charblocks, 4bpp tiles.

Note

While bgTileMem[0] has 512 elements, it’s valid to reach across into the neighbouring charblock, for example bgTileMem[0][1000].

For this reason, no bounds checking is performed on these charblocks even when compiling with --checks:on.

bgTileMem[i]      # charblock i
bgTileMem[i][j]   # charblock i, tile j

var bgTileMem8: array[4, UnboundedCharblock8]#

BG charblocks, 8bpp tiles.

bgTileMem8[i]      # charblock i
bgTileMem8[i][j]   # charblock i, tile j

var objTileMem: array[1024, Tile]#

Object (sprite) image data, as 4bpp tiles.

This is 2 charblocks in size, and is separate from BG tile memory.

Example:

objTileMem[n] = Tile()   # Clear the image data for a tile.

var objTileMem8: array[512, Tile8]#: Object (sprite) tiles, 8bpp

Screen entries#

type ScrEntry = uint16#: Type for screen entries TODO: make distinct

type ScrAffEntry = uint8#: Type for affine screen entries

type Screenline = array[32, ScrEntry]#

type ScreenMat = array[32, Screenline]#

type Screenblock = array[1024, ScrEntry]#

var seMem: array[32, Screenblock]#

Screenblocks as arrays

seMem[i]       # screenblock i
seMem[i][j]    # screenblock i, entry j
seMem[i][x,y]  # screenblock i, entry x + y*32

func tileId(se: ScrEntry): int#

func `tileId=`(se: var ScrEntry, val: int)#

func palId(se: ScrEntry): int#

func `palId=`(se: var ScrEntry, val: int)#

func hflip(se: ScrEntry): bool#

func `hflip=`(se: var ScrEntry, val: bool)#

func vflip(se: ScrEntry): bool#

func `vflip=`(se: var ScrEntry, val: bool)#

Screen entry ID shorthands#

func tid(se: ScrEntry): int#

func pal(se: ScrEntry): int#

func `tid=`(se: var ScrEntry, tid: int)#

func `pal=`(se: var ScrEntry, pal: int)#

Screen entry tile plotting#

proc fill(sbb: var Screenblock, se: ScrEntry)#: Fill screenblock sbb with se.

proc plot(sbb: var Screenblock, x, y: int, se: ScrEntry)#: Plot a screen entry at (x,`y`) of screenblock sbb.

proc hline(sbb: var Screenblock, x0, x1, y: int, se: ScrEntry)#: Draw a horizontal line on screenblock sbb with se.

proc vline(sbb: var Screenblock, x, y0, y1: int, se: ScrEntry)#: Draw a vertical line on screenblock sbb with se.

proc rect(sbb: var Screenblock, left, top, right, bottom: int, se: ScrEntry)#: Fill a rectangle on sbb with se.

proc frame(sbb: var Screenblock, left, top, right, bottom: int, se: ScrEntry)#: Create a border on sbb with se.

proc window(sbb: var Screenblock, left, top, right, bottom: int, se0: ScrEntry)#

Create a fancy rectangle.

In contrast to frame, this uses nine tiles starting at se0 for the frame, which indicate the borders and center for the window.

Note

The rectangle is not normalized. You should ensure that left < right and bottom < top.

proc clearRow(sbb: var Screenblock, row: range[0..31])#

Bitmap Drawing#

To use the bitmap drawing procedures, you have to set the appropriate bitmap mode and enable background layer 2.

e.g.

dispcnt.init(mode = 3, layers = {lBg2})

# draw a green pixel at x=100, y=100
m3mem.plot(100, 100, clrGreen)

var vidMem: array[240*160, Color]#

Main mode 3/5 frame as an array

vidMem[i]    # pixel i

var vidMemFront: array[160*128, uint16]#: First page array

var vidMemBack: array[160*128, uint16]#: Second page array

Mode 3#

type M3Line = array[240, Color]#

type M3Mem = array[160, M3Line]#

var m3Mem: array[160, M3Line]#

Mode 3 frame as a matrix

m3Mem[y][x]  # pixel (x, y)

proc fill(m: var M3Mem, clr: Color)#: Fill the mode 3 background with color clr.

proc plot(m: var M3Mem, x, y: int, clr: Color)#: Plot a single colored pixel in mode 3 at (x, y).

proc hline(m: var M3Mem, x1, y, x2: int, clr: Color)#: Draw a colored horizontal line in mode 3.

proc vline(m: var M3Mem, x, y1, y2: int, clr: Color)#: Draw a colored vertical line in mode 3.

proc line(m: var M3Mem, x1, y1, x2, y2: int, clr: Color)#: Draw a colored line in mode 3.

proc rect(m: var M3Mem, left, top, right, bottom: int, clr: Color)#

Draw a colored rectangle in mode 3.

Parameters: :left: Left side, inclusive. :top: Top size, inclusive. :right: Right size, exclusive. :bottom: Bottom size, exclusive. :clr: Color.

Note

The rectangle is normalized, but not clipped.

proc frame(m: var M3Mem, left, top, right, bottom: int, clr: Color)#

Draw a colored frame in mode 3.

Left:: Left side, inclusive.
Top:: Top size, inclusive.
Right:: Right size, exclusive.
Bottom:: Bottom size, exclusive.
Clr:: Color.

Note

The rectangle is normalized, but not clipped.

Mode 4#

type M4Line = array[240, uint8]#: NOTE: u8, not u16!! (be careful not to write single bytes to VRAM)

type M4Mem = array[160, M4Line]#

var m4Mem: array[160, M4Line]#

Mode 4 first page as a matrix Note: This is a byte-buffer. Not to be used for writing.

m4Mem[y][x]  # pixel (x, y)

var m4MemBack: array[160, M4Line]#

Mode 4 second page as a matrix This is a byte-buffer. Not to be used for writing.

m4MemBack[y][x]  = pixel (x, y)          ( u8 )

proc fill(m: var M4Mem, clrid: uint8)#: Fill the given mode 4 buffer with clrid.

proc plot(m: var M4Mem, x, y: int, clrid: uint8)#: Plot a clrid pixel on the given mode 4 buffer.

proc hline(m: var M4Mem, x1, y, x2: int, clrid: uint8)#: Draw a clrid colored horizontal line in mode 4.

proc vline(m: var M4Mem, x, y1, y2: int, clrid: uint8)#: Draw a clrid colored vertical line in mode 4.

proc line(m: var M4Mem, x1, y1, x2, y2: int, clrid: uint8)#: Draw a clrid colored line in mode 4.

proc rect(m: var M4Mem, left, top, right, bottom: int, clrid: uint8)#

Draw a clrid colored rectangle in mode 4.

Left:: Left side, inclusive.
Top:: Top size, inclusive.
Right:: Right size, exclusive.
Bottom:: Bottom size, exclusive.
Clrid:: Color index.

Note

The rectangle is normalized, but not clipped.

proc frame(m: var M4Mem, left, top, right, bottom: int, clrid: uint8)#

Draw a clrid colored frame in mode 4.

Left:: Left side, inclusive.
Top:: Top size, inclusive.
Right:: Right size, exclusive.
Bottom:: Bottom size, exclusive.
Clrid:: Color index.

Note

The rectangle is normalized, but not clipped.

Mode 5#

type M5Line = array[160, Color]#

type M5Mem = array[128, M5Line]#

var m5Mem: array[128, M5Line]#

Mode 5 first page as a matrix

m5Mem[y][x]  # pixel (x, y)

var m5MemBack: array[128, M5Line]#

Mode 5 second page as a matrix

m5MemBack[y][x]  = pixel (x, y)          ( Color )

proc fill(m: var M5Mem, clr: Color)#: Fill the given mode 5 buffer with clr.

proc plot(m: var M5Mem, x, y: int, clr: Color)#: Plot a clrid pixel on the given mode 5 buffer.

proc hline(m: var M5Mem, x1, y, x2: int, clr: Color)#: Draw a colored horizontal line in mode 5.

proc vline(m: var M5Mem, x, y1, y2: int, clr: Color)#: Draw a colored vertical line in mode 5.

proc line(m: var M5Mem, x1, y1, x2, y2: int, clr: Color)#: Draw a colored line in mode 5.

proc rect(m: var M5Mem, left, top, right, bottom: int, clr: Color)#

Draw a colored rectangle in mode 5.

Left:: Left side, inclusive.
Top:: Top size, inclusive.
Right:: Right size, exclusive.
Bottom:: Bottom size, exclusive.
Clr:: Color.

Note

The rectangle is normalized, but not clipped.

proc frame(m: var M5Mem, left, top, right, bottom: int, clr: Color)#

Draw a colored frame in mode 5.

Left:: Left side, inclusive.
Top:: Top size, inclusive.
Right:: Right size, exclusive.
Bottom:: Bottom size, exclusive.
Clr:: Color.

Note

The rectangle is normalized, but not clipped.

Objects Attribute Memory#

var objMem: array[128, ObjAttr]#

Object attribute memory

objMem[i] = object i            (ObjAttr)

var objAffMem: array[32, ObjAffine]#

Object affine memory

objAffMem[i] = object matrix i      ( OBJ_AFFINE )  

type ObjAttr = object#: Object attributes. i.e. a sprite.

Note

The fill field exists as padding for the interlace with ObjAffine. It will not be copied when assigning one ObjAttr to another.

type ObjAttrPtr = ptr ObjAttr#: Pointer to object attributes.

template initObj(args: varargs[untyped]): ObjAttr#

Create a new ObjAttr value.

Example:

objMem[0] = initObj(
  pos = vec2i(100, 100),
  size = s32x32,
  tileId = 0,
  palId = 3
)

template init(obj: ObjAttrPtr | var ObjAttr, args: varargs[untyped])#

Initialise an object in-place.

Omitted fields will default to zero.

Example:

objMem[0].init(
  pos = vec2i(100, 100),
  size = s32x32,
  tileId = 0,
  palId = 3
)

template edit(obj: ObjAttrPtr | var ObjAttr, args: varargs[untyped])#

Change some fields of an object.

Like obj.init, but omitted fields will be left unchanged.

objMem[0].edit(
  pos = vec2i(100, 100),
  size = s32x32,
  tileId = 0,
  palId = 3
)

template dup(obj: ObjAttr, args: varargs[untyped]): ObjAttr#

Duplicate an object, modifying some fields and returning the copy.

Example:

# Make a copy of Obj 0, but change some properties:
objMem[1] = objMem[0].dup(x = 100, hflip = true)

Object Fields#

type ObjMode = enum#

type ObjFxMode = enum#

type ObjSize = enum#: Sprite size constants, high-level interface. Each corresponds to a pair of fields (size in attr0, shape in attr1)

func `x=`(obj: var ObjAttr, x: int)#

func x(obj: ObjAttr): int#

func `y=`(obj: var ObjAttr, y: int)#

func y(obj: ObjAttr): int#

func `pos=`(obj: var ObjAttr, v: Vec2i)#

func pos(obj: ObjAttr): Vec2i#

func `mode=`(obj: var ObjAttr, v: ObjMode)#

func mode(obj: ObjAttr): ObjMode#

func `tileId=`(obj: var ObjAttr, tileId: int)#

func tileId(obj: ObjAttr): int#

func `fx=`(obj: var ObjAttr, v: ObjFxMode)#

func fx(obj: ObjAttr): ObjFxMode#

func `mos=`(obj: var ObjAttr, v: bool)#

func mos(obj: ObjAttr): bool#

func `hflip=`(obj: var ObjAttr, v: bool)#

func hflip(obj: ObjAttr): bool#

func `is8bpp=`(obj: var ObjAttr, v: bool)#

func is8bpp(obj: ObjAttr): bool#

func `vflip=`(obj: var ObjAttr, v: bool)#

func vflip(obj: ObjAttr): bool#

func `affId=`(obj: var ObjAttr, affId: int)#

func affId(obj: ObjAttr): int#

func `size=`(obj: var ObjAttr, v: ObjSize)#

func size(obj: ObjAttr): ObjSize#

func `palId=`(obj: var ObjAttr, palId: int)#

func palId(obj: ObjAttr): int#

func `prio=`(obj: var ObjAttr, prio: int)#

func prio(obj: ObjAttr): int#

Obj ID Shorthands#

func aff(obj: ObjAttr): int#

func `aff=`(obj: var ObjAttr, aff: int)#

func tid(obj: ObjAttr): int#

func `tid=`(obj: var ObjAttr, tid: int)#

func pal(obj: ObjAttr): int#

func `pal=`(obj: var ObjAttr, pal: int)#

Obj Helpers#

func hide(obj: var ObjAttr)#

Hide an object.

Equivalent to obj.mode = omHide

func unhide(obj: var ObjAttr, mode = omReg)#

Unhide an object.

Equivalent to obj.mode = mode

Parameters:

obj: Object to unhide.
mode: Object mode to unhide to. Necessary because this affects the affine-ness of the object.

func getSize(size: ObjSize): tuple[w, h: int]#: Get the width and height in pixels of an ObjSize enum value.

func getWidth(size: ObjSize): int#: Get the width in pixels of an ObjSize enum value.

func getHeight(size: ObjSize): int#: Get the height in pixels of an ObjSize enum value.

func getSize(size: ObjSize): tuple[w, h: int]#: Get the width and height in pixels of an ObjSize enum value.

func getWidth(size: ObjSize): int#: Get the width in pixels of an ObjSize enum value.

func getHeight(size: ObjSize): int#: Get the height in pixels of an ObjSize enum value.

func setAttr(obj: ObjAttrPtr, a0, a1, a2: uint16)#: Set the attributes of an object

func setAttr(obj: var ObjAttr, a0, a1, a2: uint16)#: Set the attributes of an object

Obj Affine Matrices#

type ObjAffine = object#: Object affine parameters.

type ObjAffinePtr = ptr ObjAffine#: Pointer to object affine parameters.

type ObjAffineSource = AffSrc#

type ObjAffineDest = AffDst#

proc init(oaff: var ObjAffine, pa, pb, pc, pd: Fixed)#

proc setToIdentity(oaff: var ObjAffine)#: Set an object affine matrix to the identity matrix.

proc setToScale(oaff: var ObjAffine, sx, sy: Fixed)#: Set an object affine matrix for scaling.

proc setToShearX(oaff: var ObjAffine, hx: Fixed)#

proc setToShearY(oaff: var ObjAffine, hy: Fixed)#

proc setToRotation(oaff: var ObjAffine, alpha: uint16)#

Set obj matrix to counter-clockwise rotation.

Oaff:: Object affine matrix to set.
Alpha:: CCW angle. full-circle is 0x10000.

proc setToScaleAndRotation(oaff: var ObjAffine, sx, sy: Fixed, alpha: uint16)#

Set obj matrix to 2d scaling, then counter-clockwise rotation.

Oaff:: Object affine matrix to set.
Sx:: Horizontal scale (zoom). .8 fixed point.
Sy:: Vertical scale (zoom). .8 fixed point.
Alpha:: CCW angle. full-circle is 0x10000.

proc setToScaleAndRotation(oaff: var ObjAffine, affSrc: ptr AffSrc)#

Set obj matrix to 2d scaling, then counter-clockwise rotation.

Oaff:: Object affine matrix to set.
AffSrc:: Struct with scales and angle.

proc premul(dst: var ObjAffine, src: ObjAffinePtr)#

Pre-multiply the matrix dst by src. i.e.

dst = src * dst

proc postmul(dst: var ObjAffine, src: ObjAffinePtr)#

Post-multiply the matrix dst by src. i.e.

dst = dst * src

proc rotscaleEx(obj: var ObjAttr, oaff: var ObjAffine, asx: ptr AffSrcEx)#

Rot/scale an object around an arbitrary point. Sets up obj and oaff for rot/scale transformation around an arbitrary point using the asx data.

Obj:: Object to set.
Oaff:: Object affine data to set.
Asx:: Affine source data: screen and texture origins, scales and angle.

proc setToScaleInv(oa: var ObjAffine, wx, wy: Fixed)#

proc setToRotationInv(oa: var ObjAffine, theta: uint16)#

proc setToShearXInv(oa: var ObjAffine, hx: Fixed)#

proc setToShearYInv(oa: var ObjAffine, hy: Fixed)#