How to Use Effects

Setup#

This example uses the headless Creative Engine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

We create a scene containing a graphic block with an image fill and want to apply effects to this image.

Accessing Effects#

Not all types of design blocks support effects, so you should always first call the hasEffects(id: number): boolean API before accessing any of the following APIs.

Note: hasEffect does not return whether the block currently has any effects attached but rather whether it supports effects in general.

Creating an Effect#

In order to add effects to our block, we first have to create a new effect instance, which we can do by calling createEffect(type: EffectType): number and passing it the type of effect that we want. In this example, we create a pixelization and an adjustment effect.

Please refer to the API docs for a complete list of supported effect types.

Adding Effects#

Now we have two effects but the output of our scene looks exactly the same as before. That is because we still need to append these effects to the graphic design block's list of effects, which we can do by calling appendEffect(id: number, effect: number): void.

We can also insert or remove effects from specific indices of a block's effect list using the insertEffect(id: number, effect: number, index: number): void and removeEffect(id: number, index: number): void APIs.

Effects will be applied to the block in the order they are placed in the block's effects list. If the same effect appears multiple times in the list, it will also be applied multiple times. In our case, the adjustments effect will be applied to the image first, before the result of that is then pixelated.

Querying Effects#

Use the getEffects(id: number): number[] API to query the ordered list of effect ids of a block.

Destroying Effects#

If we created an effect that we don't want anymore, we have to make sure to destroy it using the same destroy(id: number): void API that we also call for design blocks.

Effects that are attached to a design block will be automatically destroyed when the design block is destroyed.

Effect Properties#

Just like design blocks, effects with different types have different properties that you can query and modify via the API. Use findAllProperties(id: number): string[] in order to get a list of all properties of a given effect.

Please refer to the API docs for a complete list of all available properties for each type of effect.

Once we know the property keys of an effect, we can use the same APIs as for design blocks in order to modify those properties.

Our adjustment effect here for example will not modify the output unless we at least change one of its adjustment properties - such as the brightness - to not be zero.

Disabling Effects#

You can temporarily disable and enable the individual effects using the setEffectEnabled(id: number, enabled: boolean): void API. When the effects are applied to a block, all disabled effects are simply skipped. Whether an effect is currently enabled or disabled can be queried with isEffectEnabled(id: number): boolean.