PILE Base: pRect

pRect provides functions for placing and mutating axis-aligned rectangles.

Dependencies: pAssert, pInterp, pMath, pName

local pRect = require("p_rect")

local r1 = {x=0, y=0, w=16, h=16}
local r2 = {x=0, y=0, w=8, h=8}
pRect.copy(r1, r2)

print(r2.w, r2.h) --> 16 16

Table of Contents

API
Module Notes
- Omissions
- Structures
  - Rectangle
  - SideDelta

API

pRect.center

Centers Rectangle b within Rectangle a.

pRect.center(a, b)

a: The reference Rectangle.
b: The Rectangle to center.

Returns: a, for method chaining.

pRect.centerHorizontal

Horizontally centers Rectangle b within Rectangle a.

pRect.centerHorizontal(a, b)

a: The reference Rectangle.
b: The Rectangle to center.

Returns: a, for method chaining.

pRect.centerVertical

Vertically centers Rectangle b within Rectangle a.

pRect.centerVertical(a, b)

a: The reference Rectangle.
b: The Rectangle to center.

Returns: a, for method chaining.

pRect.copy

Overwrites the position and dimensions of Rectangle b with those of a.

pRect.copy(a, b)

a: The source Rectangle.
b: The Rectangle to overwrite.

Returns: a, for method chaining.

pRect.expand

Expands a Rectangle by shifting its sides.

pRect.expand(r, x1, y1, x2, y2)

r: The Rectangle to expand.
x1, y1: How much to expand the left and top sides.
x2, y2: How much to expand the right and bottom sides.

Returns: r, for method chaining.

pRect.expandBottom

Expands a Rectangle’s bottom side.

pRect.expandBottom(r, y2)

r: The Rectangle to change.
y2: How much to expand the bottom side.

Returns: r, for method chaining.

pRect.expandHorizontal

Expands a Rectangle’s left and right sides.

pRect.expandHorizontal(r, x1, x2)

r: The Rectangle to change.
x1, x2: How much to expand the left and right sides.

Returns: r, for method chaining.

pRect.expandLeft

Expand a Rectangle’s left side.

pRect.expandLeft(r, x1)

r: The Rectangle to change.
x1: How much to expand the left side.

Returns: r, for method chaining.

pRect.expandRight

Expands a Rectangle’s right side.

pRect.expandRight(r, x2)

r: The Rectangle to change.
x2: How much to expand the right side.

Returns: r, for method chaining.

pRect.expandT

Expands a Rectangle by shifting its sides. Like pRect.expand, but takes a SideDelta.

pRect.expandT(r, sd)

r: The Rectangle to change.
sd: The SideDelta to use.

Returns: r, for method chaining.

pRect.expandTop

Expands a Rectangle’s top side.

pRect.expandTop(r, y1)

r: The Rectangle to change.
y1: How much to expand the top side.

Returns: r, for method chaining.

pRect.expandVertical

Expands a Rectangle’s top and bottom sides.

pRect.expandVertical(r, y1, y2)

r: The Rectangle to change.
y1, y2: How much to expand the top and bottom sides.

Returns: r, for method chaining.

pRect.flipHorizontal

Horizontally flips a Rectangle within another Rectangle.

pRect.flipHorizontal(a, b)

a: The reference Rectangle.
b: The Rectangle to flip.

Returns: a, for method chaining.

pRect.flipVertical

Vertically flips a Rectangle within another Rectangle.

pRect.flipVertical(a, b)

a: The reference Rectangle.
b: The Rectangle to flip.

Returns: a, for method chaining.

pRect.getBounds

Gets the horizontal and vertical ranges of a group of Rectangles.

local x1, y1, x2, y2 = pRect.getBounds(...)

…: A vararg list of Rectangles.

Returns: The furthest left, top, right and bottom positions.

Notes

If no Rectangles are provided, this function will return zero for all positions.

pRect.getBoundsT

Gets the horizontal and vertical ranges of a group of Rectangles. Like pRect.getBounds, but takes an array instead of a vararg list.

local x1, y1, x2, y2 = pRect.getBoundsT(list)

list: An array of Rectangles.

Returns: The furthest left, top, right and bottom positions.

Notes

If there are no elements in the array, this function will return zero for all positions.

pRect.placeInner

Places Rectangle b within the boundaries of Rectangle a at an interpolated position.

pRect.placeInner(a, b, ux, uy)

a: The reference Rectangle.
b: The Rectangle to place.
ux, uy: The horizontal and vertical positions; numbers from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

a is assumed to be at least as big as b.

The final coordinates of b are rounded to integers.

pRect.placeInnerHorizontal

Horizontally places Rectangle b within the boundaries of Rectangle a at an interpolated position.

pRect.placeInnerHorizontal(a, b, ux)

a: The reference Rectangle.
b: The Rectangle to place.
ux: The horizontal position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.placeInnerVertical

Vertically places Rectangle b within the boundaries of Rectangle a at an interpolated position.

pRect.placeInnerVertical(a, b, uy)

a: The reference Rectangle.
b: The Rectangle to place.
uy: The vertical position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.placeMidpoint

Places Rectangle b's center point within the boundaries of Rectangle a, at an interpolated position.

pRect.placeMidpoint(a, b, ux, uy)

a: The reference Rectangle.
b: The Rectangle to place.
ux, uy: The horizontal and vertical positions; numbers from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

The final coordinates of b are rounded to integers.

pRect.placeMidpointHorizontal

Horizontally places Rectangle b's center point within the boundaries of Rectangle a, at an interpolated position.

pRect.placeMidpointHorizontal(a, b, ux)

a: The reference Rectangle.
b: The Rectangle to place.
ux: The horizontal position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.placeMidpointVertical

Vertically places Rectangle b's center point within the boundaries of Rectangle a, at an interpolated position.

pRect.placeMidpointVertical(a, b, uy)

a: The reference Rectangle.
b: The Rectangle to place.
uy: The vertical position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.placeOuter

Places Rectangle b within or just outside the boundaries of Rectangle a at an interpolated position.

pRect.placeOuter(a, b, ux, uy)

a: The reference Rectangle.
b: The Rectangle to place.
ux, uy: The horizontal and vertical positions; numbers from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

The final coordinates of b are rounded to integers.

pRect.placeOuterHorizontal

Horizontally places Rectangle b within or just outside the boundaries of Rectangle a at an interpolated position.

pRect.placeOuterHorizontal(a, b, ux)

a: The reference Rectangle.
b: The Rectangle to place.
ux: The horizontal position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.placeOuterVertical

Vertically places Rectangle b within or just outside the boundaries of Rectangle a at an interpolated position.

pRect.placeOuterVertical(a, b, uy)

a: The reference Rectangle.
b: The Rectangle to place.
uy: The vertical position; a number from 0.0 to 1.0.

Returns: a, for method chaining.

pRect.pointOverlap

Checks if a point is within a Rectangle.

local overlap = pRect.pointOverlap(r, x, y)

r: The Rectangle to check.
x, y: The point’s position.

Returns: true if the point overlaps the Rectangle, false if not.

pRect.reduce

Shortens a Rectangle by shifting its sides.

pRect.reduce(r, x1, y1, x2, y2)

r: The Rectangle to expand.
x1, y1: How much to shorten the left and top sides.
x2, y2: How much to shorten the right and bottom sides.

Returns: r, for method chaining.

pRect.reduceBottom

Shortens a Rectangle’s bottom side.

pRect.reduceBottom(r, y2)

r: The Rectangle to change.
y2: How much to shorten the bottom side.

Returns: r, for method chaining.

pRect.reduceHorizontal

Shortens a Rectangle’s left and right sides.

pRect.reduceHorizontal(r, x1, x2)

r: The Rectangle to change.
x1, x2: How much to shorten the left and right sides.

Returns: r, for method chaining.

pRect.reduceLeft

Shortens a Rectangle’s left side.

pRect.reduceLeft(r, x1)

r: The Rectangle to change.
x1: How much to shorten the left side.

Returns: r, for method chaining.

pRect.reduceRight

Shortens a Rectangle’s right side.

pRect.reduceRight(r, x2)

r: The Rectangle to change.
x2: How much to shorten the right side.

Returns: r, for method chaining.

pRect.reduceT

Shortens a Rectangle by shifting its sides. Like pRect.reduce, but takes a SideDelta.

pRect.reduceT(r, sd)

r: The Rectangle to shorten.
sd: The SideDelta to use.

Returns: r, for method chaining.

pRect.reduceTop

Shortens a Rectangle’s top side.

pRect.reduceTop(r, y1)

r: The Rectangle to change.
y1: How much to shorten the top side.

Returns: r, for method chaining.

pRect.reduceVertical

Shortens a Rectangle’s top and bottom sides.

pRect.reduceVertical(r, y1, y2)

r: The Rectangle to change.
y1, y2: How much to shorten the top and bottom sides.

Returns: r, for method chaining.

pRect.set

Sets a Rectangle’s position and dimensions.

pRect.set(r, x, y, w, h)

r: The Rectangle to modify.
x, y: The new position.
w, h: The new dimensions.

Returns: r, for method chaining.

pRect.setDimensions

Sets a Rectangle’s dimensions.

pRect.setDimensions(r, w, h)

r: The Rectangle to modify.
w, h: The new dimensions.

Returns: r, for method chaining.

pRect.setPosition

Sets a Rectangle’s position.

pRect.setPosition(r, x, y)

r: The Rectangle to modify.
x, y: The new position.

Returns: r, for method chaining.

pRect.split

Splits a Rectangle.

pRect.split(a, b, side, len)

a: The input Rectangle.
b: The output Rectangle (to be assigned the removed part of a).
side: The side to split: left, right, top, or bottom.
len: The length of the split.

Returns: a, for method chaining.

pRect.splitBottom

Shortens Rectangle a by cutting a chunk from its bottom side, and overwrites Rectangle b to match the chunk.

pRect.splitBottom(a, b, len)

a: The Rectangle to shorten.
b: The Rectangle to be assigned the removed part.

Returns: a, for method chaining.

pRect.splitLeft

Shortens Rectangle a by cutting a chunk from its left side, and overwrites Rectangle b to match the chunk.

pRect.splitLeft(a, b, len)

a: The Rectangle to shorten.
b: The Rectangle to be assigned the removed part.

Returns: a, for method chaining.

pRect.splitOrOverlay

Splits or copies a Rectangle, based on the arguments provided.

pRect.splitOrOverlay(a, b, placement, len)

a: The input Rectangle.
b: The output Rectangle.
placement: How to place Rectangle b: by splitting Rectangle a (left, right, top, bottom), or by copying it (overlay).
len: The length of the split. Not used when the placement mode is overlay.

Returns: a, for method chaining.

pRect.splitRight

Shortens Rectangle a by cutting a chunk from its right side, and overwrites Rectangle b to match the chunk.

pRect.splitRight(a, b, len)

a: The Rectangle to shorten.
b: The Rectangle to be assigned the removed part.

Returns: a, for method chaining.

pRect.splitTop

Shortens Rectangle a by cutting a chunk from its top side, and overwrites Rectangle b to match the chunk.

pRect.splitTop(a, b, len)

a: The Rectangle to shorten.
b: The Rectangle to be assigned the removed part.

Returns: a, for method chaining.

Module Notes

Omissions

Functions that would only change one variable in a trivial way, like setX() or setHeight(), are omitted from the API.

Structures

pRect does not come with functions to create the following structures. Any table that contains the expected fields may be used. Out of concern for overhead, function arguments are not validated by default.

Rectangle

A table with x, y, w and h fields, all numbers. The width and height are assumed to be greater than or equal to zero.

local rect = {x=0, y=0, w=0, h=0}

SideDelta

A table with measurements for each side of a rectangle. These are typically used to apply margins, padding, etc.

local sd = {x1=0, y1=0, x2=0, y2=0} -- left, top, right, bottom

VERSION: 2.106