FxPixelLayer

This module contains functions for PixelLayer nodes.

INFO

Source grids and pixels define the data on which the functions of this module operate.

A source node is any PixelLayer node identified by the given NodeID.

A source grid is the pixel grid of a source node.

The source pixels are all pixels of the source grid, unless the NodeID wildcard /a is used and the active node is a PixelLayer whose grid has selected pixels. In this case, only the selected pixels are the source pixels.

Load

FxPixelLayer = require "FxPixelLayer";

Functions

Function	Description
AdjustHeight (NodeID, Offset)	Adds an offset to the height of pixels.
AssignHeight (NodeID, Value)	Sets the height of pixels.
BrightnessContrast (NodeID, Brightness, Contrast)	Roughly adjusts brightness and contrast.
Clear (NodeID)	Deletes all pixels.
ColorOverlay (NodeID, Color, Opacity)	Blends the color of pixels with another color.
Crop (NodeID, X, Y, Width, Height)	Crops a pixel grid.
Desaturate (NodeID)	Roughly desaturates pixel.
Detach (NodeID)	Moves selected pixels to a new layer.
Fill (NodeID, Pixel)	Sets all solid pixels.
FillColor (NodeID, Color)	Sets the color of pixels.
FillMaterial (NodeID, Material)	Sets the material of pixels.
Flip (NodeID, Horizontally)	Flips a pixel grid.
HueSaturation (NodeID, Hue, Saturation, Lightness)	Roughly adjusts hue, saturation and lightness.
InvertColors (NodeID)	Roughly inverts colors.
Merge (NodeID1, NodeID2)	Merges two pixel layers.
Mirror (NodeID, Direction)	Mirrors a pixel grid.
OptimizeSize (NodeID)	Crops empty areas.
ReduceColors (NodeID, ColorCount)	Reduces the number of distinct colors used in the pixel grid.
ReplaceColor (NodeID, Color, ReplacementColor)	Replaces colors of pixels.
ReplaceMaterial (NodeID, Material, ReplacementMaterial)	Replaces materials of pixels.
Resize (NodeID, X, Y, AnchorX, AnchorY)	Resizes a pixel grid.
Rotate (NodeID, Angle)	Rotates a pixel grid arbitrarily.
Rotate90 (NodeID, Steps)	Rotates a pixel grid in 90° steps.
Scale (NodeID, X, Y)	Scales a pixel grid.
ScaleToFit (NodeID, X, Y, AnchorX, AnchorY)	Resizes a pixel grid and scales its content to fit the new size.
Shear (NodeID, ShearFactorX, ShearFactorY)	Skews a pixel grid.
WrapAround (NodeID, X, Y)	Offsets pixels. Pixels pushed out are moved to the opposite side.

AdjustHeight (NodeID, Offset)

This function adds the specified offset to the height of all source pixels.

Parameters

• NodeID: The NodeID to identify the source nodes
• Offset: The value added to the height

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.AdjustHeight("layer1", 2);

AssignHeight (NodeID, Value)

This function sets the height of all source pixels to the specified value.

Parameters

• NodeID: The NodeID to identify the source nodes
• Value: The new pixel height

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.AssignHeight("layer1", 20);

BrightnessContrast (NodeID, Brightness, Contrast)

This function roughly adjusts the brightness and contrast of the source grid. For each source pixel the adjusted color is calculated, then the index color that best matches the calculated color is determined and assigned to the pixel.

Parameters

• NodeID: The NodeID to identify the source nodes
• Brightness: The brightness shift, clamped to [-1.0, 1.0]
• Contrast: The contrast shift, clamped to [-1.0, 1.0]

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

-- shift brightness by 0.5
FxPixelLayer.BrightnessContrast("layer1", 0.5, 0);

Clear (NodeID)

This function deletes all source pixels.

Parameters

• NodeID: The NodeID to identify the source nodes

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Clear("layer1");

ColorOverlay (NodeID, Color, Opacity)

This function roughly blends the source grid with a color and opacity. For each source pixel, the adjusted color is calculated, then the index color that best matches the calculated color is determined and assigned to the pixel.

Parameters

• NodeID: The NodeID to identify the source nodes
• Color: Blend Color
• Opacity: Blend Opacity

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

color = FxColor.CreateFromHex("ff00ff");
FxPixelLayer.ColorOverlay("layer1", color, 0.5);

Crop (NodeID, X, Y, Width, Height)

This function cuts off areas of the source grid outside of the specified area.

Parameters

• NodeID: The NodeID to identify the source nodes
• X: The X coordinate of the area position
• Y: The Y coordinate of the area position
• Width: The area width
• Height: The area height

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.Crop("layer1", 5, 5, 10, 10);

Desaturate (NodeID)

This function roughly reduces the saturation of the source grid to 0.0. For each source pixel the adjusted color is calculated, then the index color that best matches the calculated color is determined and assigned to the pixel.

Parameters

• NodeID: The NodeID to identify the source nodes

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Desaturate("layer1");

Detach (NodeID)

This function moves all selected pixels from the source grid to a new PixelLayer node.

Parameters

• NodeID: The NodeID of the PixelLayer node

Returns

The NodeID of the new PixelLayer

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Detach("layer1");

Fill (NodeID, Pixel)

This function replaces all solid source pixels with the specified pixel.

Parameters

• NodeID: The NodeID to identify the source nodes
• Value: The fill FoxelPixel

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

pixel = FxPixel.Create(0, 0);
FxPixelLayer.Fill("layer1", pixel);

FillColor (NodeID, Color)

This function assigns the given color to all source pixels.

Parameters

• NodeID: The NodeID to identify the source nodes
• Color: The color ItemIndex

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_ITEM_INDEX_INVALID

Since

Version 1.0

Example

FxPixelLayer.FillColor("layer1", 10);

FillMaterial (NodeID, Material)

This function applies the given material to all source pixels.

Parameters

• NodeID: The NodeID to identify the source nodes
• Material: The material ItemIndex

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_ITEM_INDEX_INVALID

Since

Version 1.0

Example

FxPixelLayer.FillMaterial("layer1", 1);

Flip (NodeID, Horizontally)

This function flips the source grid.

Parameters

• NodeID: The NodeID to identify the source nodes
• Horizontally: Whether to flip horizontally

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

-- flip vertically
FxPixelLayer.Flip("layer1", false);

HueSaturation (NodeID, Hue, Saturation, Lightness)

This function roughly adjusts the hue, saturation, and lightness of the source grid. For each source pixel, the adjusted color is calculated, then the index color that best matches the calculated color is determined and assigned to the pixel.

Parameters

• NodeID: The NodeID to identify the source nodes
• Hue: The hue shift, clamped to [-1.0, 1.0]
• Saturation: The saturation shift, clamped to [-1.0, 1.0]
• Lightness: The lightness shift, clamped to [-1.0, 1.0]

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.HueSaturation("layer1", -0.2, -0.5, 0);

InvertColors (NodeID)

This function roughly inverts the colors of the source grid. For each source pixel the adjusted color is calculated, then the index color that best matches the calculated color is determined and assigned to the pixel.

Parameters

• NodeID: The NodeID to identify the source nodes

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.InvertColors("layer1");

Merge (NodeID1, NodeID2)

This function merges the two grids of the given nodes and deletes the second node.

Parameters

• NodeID1: The NodeID of the first PixelLayer node
• NodeID2: The NodeID of the second PixelLayer node

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Merge("layer1", "layer2");

Mirror (NodeID, Direction)

This function mirrors one half of the source grid to the other depending on the given direction.

Parameters

• NodeID: The NodeID to identify the source nodes
• Direction: The mirror Direction2D

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.Mirror("layer1", 1);

OptimizeSize (NodeID)

This function cuts the surrounding empty areas from the source grid.

Parameters

• NodeID: The NodeID to identify the source nodes

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.OptimizeSize("layer1");

ReduceColors (NodeID, ColorCount)

This function reduces the number of colors used in the specified source pixels.

Parameters

• NodeID: The NodeID that identifies the source nodes.
• ColorCount: The target number of colors to be used by the source pixels.

Errors

Possible errors include: FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID.

Since

Version 1.0

Example

FxPixelLayer.ReduceColors("layer1", 10);

ReplaceMaterial (NodeID, Material, ReplacementMaterial)

This function assigns the specified new material to all source pixels that have Material assigned.

Parameters

• NodeID: The NodeID to identify the source nodes
• Material: The material ItemIndex to look for
• ReplacementMaterial: The material ItemIndex to replace with

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_ITEM_INDEX_INVALID

Since

Version 1.0

Example

FxPixelLayer.ReplaceMaterial("layer1", 0, 1);

ReplaceColor (NodeID, Color, ReplacementColor)

This function assigns the specified new color to all source pixels that have Color assigned.

Parameters

• NodeID: The NodeID to identify the source nodes
• Color: The color ItemIndex to look for
• ReplacementColor: The color ItemIndex to replace with

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_ITEM_INDEX_INVALID

Since

Version 1.0

Example

FxPixelLayer.ReplaceColor("layer1", 0, 1);

Resize (NodeID, X, Y, AnchorX, AnchorY)

This function resizes the source grid from given anchors and optionally resamples its contents.

Parameters

• NodeID: The NodeID to identify the source nodes
• X: New pixel grid width
• Y: New pixel grid height
• AnchorX: The X-axis Anchor
• AnchorY: The Y-axis Anchor

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.Resize("layer1", 20, 30, 0, 0);

Rotate (NodeID, Angle)

This function rotates the source grid arbitrarily.

Parameters

• NodeID: The NodeID to identify the source nodes
• Angle: The rotation angle in degrees

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Rotate("layer1", 45);

Rotate90 (NodeID, Steps)

This function rotates the source grid by the specified number of 90° steps.

Parameters

• NodeID: The NodeID to identify the source nodes
• Steps: The number of 90° rotation steps

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.Rotate90("layer1", 1);

Scale (NodeID, X, Y)

This function scales the source grid.

Parameters

• NodeID: The NodeID to identify the source nodes
• X: X-axis scaling
• X: Y-axis scaling

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.Scale("layer1", 0.25, 0.25);

ScaleToFit (NodeID, X, Y, AnchorX, AnchorY)

This function resizes the source grid from given anchors and scales its content to fit the new size.

Parameters

• NodeID: The NodeID to identify the source nodes
• X: The new voxel grid width
• Y: The new voxel grid height
• AnchorX: The X-axis Anchor
• AnchorY: The Y-axis Anchor

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.ScaleToFit("layer1", 20, 30, 0, 0);

Shear (NodeID, ShearFactorX, ShearFactorY)

This function skews the source grid by the specified factors.

Parameters

• NodeID: The NodeID to identify the source nodes
• ShearFactorX: The Shear factor for the X-axis
• ShearFactorY: The Shear factor for the Y-axis

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_VALUE_INVALID

Since

Version 1.0

Example

FxPixelLayer.Shear("layer1", 1.0, 2.0);

WrapAround (NodeID, X, Y)

This function offsets the grid position of source pixels. The pixels that are pushed out are moved to the opposite side.

Parameters

• NodeID: The NodeID to identify the source nodes
• X: The X-axis offset
• Y: The Y-axis offset

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND

Since

Version 1.0

Example

FxPixelLayer.WrapAround("layer1", 0, 10);