arsd.pixmappaint

Colors

Colors are stored in an RGBA format with 8 bit per channel. See Pixel for details.

The coordinate system

The top left corner of a pixmap is its origin (0,0).

The $(horizontal axis) is called x. Its corresponding length/dimension is known as width.

The letter y is used to describe the vertical axis. Its corresponding length/dimension is known as height.

0 → x
↓
y

Furthermore, length refers to the areal size of a pixmap. It represents the total number of pixels in a pixmap. It follows from the foregoing that the term long usually refers to the length (not the width).

Pixmaps

A Pixmap consist of two fields:

• a slice (of an array of Pixels)
• a width

This design comes with many advantages. First and foremost it brings simplicity.

Pixel data buffers can be reused across pixmaps, even when those have different sizes. Simply slice the buffer to fit just enough pixels for the new pixmap.

Memory management can also happen outside of the pixmap. It is possible to use a buffer allocated elsewhere. (Such a one shouldn’t be mixed with the built-in memory management facilities of the pixmap type. Otherwise one will end up with GC-allocated copies.)

The most important downside is that it makes pixmaps basically a partial reference type.

Copying a pixmap creates a shallow copy still poiting to the same pixel data that is also used by the source pixmap. This implies that manipulating the source pixels also manipulates the pixels of the copy – and vice versa.

The issues implied by this become an apparent when one of the references modifies the pixel data in a way that also affects the dimensions of the image; such as cropping.

Pixmaps describe how pixel data stored in a 1-dimensional memory space is meant to be interpreted as a 2-dimensional image.

A notable implication of this 1D ↔ 2D mapping is, that slicing the 1D data leads to non-sensical results in the 2D space when the 1D-slice is reinterpreted as 2D-image.

Especially slicing across scanlines (→ horizontal rows of an image) is prone to such errors.

(Slicing of the 1D array data can actually be utilized to cut off the bottom part of an image. Any other naiv cropping operations will run into the aforementioned issues.)

Image manipulation

The term “image manipulation function” here refers to functions that manipulate (e.g. transform) an image as a whole.

Image manipulation functions in this library are provided in up to three flavors:

• a “source to target” function
• a “source to newly allocated target” wrapper
• optionally an “in-place” adaption

Additionally, a “compute dimensions of target” function is provided.

Source to Target

The regular “source to target” function takes (at least) two parameters: A source Pixmap and a target Pixmap.

(Additional operation-specific arguments may be required as well.)

The target pixmap usually needs to be able to fit at least the same number of pixels as the source holds. Use the corresponding “compute size of target function” to calculate the required size when needed. (A notable exception would be cropping, where to target pixmap must be only at least long enough to hold the area of the size to crop to.)

The data stored in the buffer of the target pixmap is overwritten by the operation.

A modified Pixmap structure with adjusted dimensions is returned.

These functions are named plain and simple after the respective operation they perform; e.g. flipHorizontally or crop.

// Allocate a new target Pixmap.
Pixmap target = Pixmap.makeNew(
	flipHorizontallyCalcDims(sourceImage)
);

// Flip the image horizontally and store the updated structure.
// (Note: As a horizontal flip does not affect the dimensions of a Pixmap,
//        storing the updated structure would not be necessary
//        in this specific scenario.)
target = sourceImage.flipHorizontally(target);

const cropOffset = Point(0, 0);
const cropSize = Size(100, 100);

// Allocate a new target Pixmap.
Pixmap target = Pixmap.makeNew(
	cropCalcDims(sourceImage, cropSize, cropOffset)
);

// Crop the Pixmap.
target = sourceImage.crop(target, cropSize, cropOffset);

Source to New Target

The “source to newly allocated target” wrapper allocates a new buffer to hold the manipulated target.

These wrappers are provided for user convenience.

They are identified by the suffix -New that is appended to the name of the corresponding “source to target” function; e.g. flipHorizontallyNew or cropNew.

// Create a new flipped Pixmap.
Pixmap target = sourceImage.flipHorizontallyNew();

const cropOffset = Point(0, 0);
const cropSize = Size(100, 100);

// Create a new cropped Pixmap.
Pixmap target = sourceImage.cropNew(cropSize, cropOffset);

In-Place

For selected image manipulation functions a special adaption is provided that stores the result in the source pixel data buffer.

Depending on the operation, implementing in-place transformations can be either straightforward or a major undertaking (and topic of research). This library focuses and the former and leaves out cases where the latter applies. In particular, algorithms that require allocating further buffers to store temporary results or auxiliary data will probably not get implemented.

Furthermore, operations where to result is longer than the source cannot be performed in-place.

Certain in-place manipulation functions return a shallow-copy of the source structure with dimensions adjusted accordingly. This is behavior is not streamlined consistently as the lack of an in-place option for certain operations makes them a special case anyway.

These function are suffixed with -InPlace; e.g. flipHorizontallyInPlace or cropInPlace.

image.flipHorizontallyInPlace();

const cropOffset = Point(0, 0);
const cropSize = Size(100, 100);

image = image.cropInPlace(cropSize, cropOffset);

Compute size of target

Functions to “compute (the) dimensions of (a) target” are primarily meant to be utilized to calculate the size for allocating new pixmaps to be used as a target for manipulation functions.

They are provided for all manipulation functions even in cases where they are provide little to no benefit. This is for consistency and to ease development.

Such functions are identified by a -CalcDims suffix; e.g. flipHorizontallyCalcDims or cropCalcDims.

They usually take the same parameters as their corresponding “source to new target” function. This does not apply in cases where certain parameters are irrelevant for the computation of the target size.