Name
SetLayerFilter -- enable/disable filters for layer (V5.0)
Synopsis
SetLayerFilter(layer, table)
Function
This command can be used to control which filters are applied to a layer, and in what order they will be applied to the layer. You have to pass a table to this function that contains a number of subtables, each of which contains information for a single layer filter. The following tags are supported for each subtable:

Name
Contains the name of the filter that this subtable element shall configure. This tag is mandatory and must always be specified in every subtable so that SetLayerFilter() knows the filter the subtable is addressing. Please see below for a list of supported filter types.

Args
Contains an array of arguments for the filter specified in the Name tag. The values passed here depend on the filter specified. Some filters like XFlip or Gray do not require any arguments at all. In that case, you do not have to pass the Args table. Please see below to learn about the arguments required by the single filters. Also note that SetLayerFilter() has fallback arguments for every filter it supports. Thus, you can also leave out arguments. In that case, SetLayerFilter() will use its default settings for the respective filter.

Disable
This tag can be used to enable or disable a filter. Pass False here to enable the filter, or True to disable it. This tag is optional. If it is not specified, the filter will get enabled by default.

Priority
This tag allows you to specify a priority level for the current filter. A priority level is simply a numeric value which is then used by SetLayerFilter() to find out the order in which the filters should be applied. The priority level must be between 0 (= lowest priority) and 255 (= highest priority). As an example, if you assign a priority of 10 to the Blur filter, and a priority of 9 to the Tint filter, the blur filter will be applied before the tint filter. This tag will default to 0 if not specified.

A list of supported layer filters follows below. Please note that the arguments must not be passed to the filter as a named table tag but sequentially in the Args array. I.e. for the Modulate filter, you would put the brightness setting in array element 0, the saturation setting in array element 1, and the hue setting in element 2. The order in which the single arguments are listed below corresponds to the order in which they are expected in the Args table. Here is the list now:

Blur
This filter will apply a Gaussian blur to the layer. The following arguments need to be passed:

Radius:
Specifies the blur radius. The greater the value you specify here, the longer the blurring will take.

Charcoal
This filter will apply a charcoal filter to the layer. The following arguments need to be passed:

Radius:
Specifies the effect radius. The greater the value you specify here, the longer the calculation will take.

Contrast
This filter will enhance or reduce color contrast in the layer. The following arguments need to be passed:

Inc:
Pass True here to enhance the color contrast, or False to decrease the color contrast.

Repeat:
Specifies how many times the effect should be repeated. This is useful for a more pronounced effect. By default this is set to 1 which means that the effect is only applied once. If you would like to have two passes, specify 2 here, etc. Remember that the greater the number you specify here is, the longer the computation of the result will take.

Edge
This filter will apply an edge detection filter to the layer. The following arguments need to be passed:

Radius:
Specifies the effect radius. The greater the value you specify here, the longer the calculation will take.

Emboss
This filter will apply an emboss filter to the layer. The following arguments need to be passed:

Radius:
Specifies the effect radius. The greater the value you specify here, the longer the calculation will take.

Gamma
This filter can be used to apply gamma correction to the layer. The following arguments need to be passed:

Red:
Gamma correction for red color channel.

Green:
Gamma correction for green color channel.

Blue:
Gamma correction for blue color channel.

Each value must be floating point value. A value of 1.0 means no change, a value smaller than 1.0 darkens the channel, a value greater than 1.0 lightens it. See GammaBrush for details.

Grayscale
This filter will map the layer to gray. There are no arguments for this filter.

Invert
This filter will invert the colors of the layer. There are no arguments for this filter.

Modulate
This filter can be used to modulate brightness, saturation, and hue values of a layer. The following arguments need to be passed:

Brightness:
Desired brightness modulation.

Saturation:
Desired saturation modulation.

Hue:
Desired hue modulation.

Each value must be floating point value. A value of 1.0 means no change, a value smaller than 1.0 reduces the brightness/saturation/hue, while a value greater than 1.0 enhances it. See ModulateBrush for details.

Monochrome
This filter will apply a black and white filter to this layer. The following arguments need to be passed:

Dither:
Specifies whether or not dithering should be used. Pass True or False here. Dithering looks better, but is of course slower.

OilPaint
This filter will apply an oil paint filter to the layer. The following arguments need to be passed:

Radius:
Specifies the effect radius. The greater the value you specify here, the longer the calculation will take.

Pixelate
This filter will zoom the pixel cells of the layer to the specified size. The following arguments need to be passed:

CellSize:
Specifies the desired zoom size. Every pixel of the layer will be zoomed to this size, starting from the top-left corner of the layer.

See PixelateBrush for details.

Quantize
This filter will reduce the number of colors in the layer. The following arguments need to be passed:

Colors:
Desired number of colors. This must be between 1 and 256.

Dither:
True to enable dithering, False to disable it.

See QuantizeBrush for details. (V6.0)

SepiaTone
Applies a sepia-tone filter to the layer. The following arguments need to be passed:

Level:
Desired sepia-toning level. This must be between 0 and 255, or alternatively it can be a string containing a percentage specification. The usual setting is "80%" (i.e. a level of about 204).

See SepiaToneBrush for details.

Sharpen
Applies a sharpening filter to the layer. The following arguments need to be passed:

Radius:
Specifies the sharpen radius. The greater the value you specify here, the longer the calculation will take.

Solarize
Applies a solarization effect to the layer. The following arguments need to be passed:

Level:
Desired solarization level (must be between 0 and 255).

See SolarizeBrush for details.

Swirl
Swirls the layer by the specified number of degrees. The following arguments need to be passed:

Degrees:
Specifies the desired swirling amount. This can be between 0 (no swirling) and 360 (full swirl).

Tint
This filter will tint the layer with the specified color at the specified ratio. The following arguments need to be passed:

Color:
Specifies the tinting color in RGB format.

Ratio:
Specifies the tinting ratio. This can be a value between 0 (= no tinting) and 255 (= full tinting), or a string containing a percentage specification (e.g. "50%" corresponds to a ratio of 128).

WaterRipple
This filter will apply water ripples to the layer. The following arguments need to be passed:

Wavelength:
Desired wavelength for the effect.

Ampltiude:
Desired ripple amplitude.

Phase:
Desired ripple phase.

CX:
X center point of water ripple.

CY:
Y center point of water ripple.

See WaterRippleBrush for details.

XFlip
This will mirror the layer on the x-axis. There are no arguments for this filter.

YFlip
This will mirror the layer on the y-axis. There are no arguments for this filter.

To disable all layer filters, you can pass the special value 0 instead of a table in the second argument. SetLayerFilter() will then cancel all filters that are currently active on the specified layer.

Please note that this command will not reset any existing filter settings when it is called. Instead, all existing filters settings will be kept and the new settings will merely be merged with the old ones. So if you have a layer that has several filters attached and you only want to change the configuration of one of these filters, it is sufficient to just pass a subtable for this single filter to SetLayerFilter(). It is not necessary to pass all the other filters to SetLayerFilter() again.

Also note that layer filters can get quite heavy on the CPU; especially when using transition effects on a layer that has filters attached. In that case, the filters have to be recalculated for each new frame of the transition effect. Depending on the complexity of the filter, this can take some time.

You can also use the SetLayerStyle() command to change the configuration of one or more layer filters.

Inputs
layer
layer to modify
table
a table containing one or more subtables that contain a description of filters to apply to or remove from the layer; see above for more information; to remove all filters from a layer, pass 0 here instead of a table
Example
table = {
{Name = "YFlip"},
{Name = "Modulate", Args = {1.0, 2.0, 1.0}, Priority = 10},
{Name = "Swirl", Args = {128}, Priority = 9} }
SetLayerFilter(1, table)
The code above increases the saturation of layer 1 by 200%, swirls the layer by 180 degrees and then mirrors it on the y-axis.


SetLayerFilter(1, {{Name = "YFlip", Disable = True}})
The code above removes the "YFlip" filter from layer 1 but keeps the other two filters (modulate and swirl).

Show TOC