SetLayerFilter(layer, table)

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.

Starting with Hollywood 10.0, this function can also operate on layer groups so you can also pass the name of a layer group to this function.

layer

layer or layer group to use

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

table = {
{Name = "YFlip"},
{Name = "Modulate", Args = {1.0, 2.0, 1.0}, Priority = 10},
{Name = "Swirl", Args = {128}, Priority = 9} }
SetLayerFilter(1, table)

SetLayerFilter(1, {{Name = "YFlip", Disable = True}})