Skip to content

Add a Filter or Effect

Some design blocks in CE.SDK such as pages and graphic blocks allow you to add effects to them. An effect can modify the visual output of a block’s fill. CreativeEditor SDK supports many different types of effects, such as adjustments, LUT filters, pixelization, glow, vignette and more.

Similarly to blocks, each effect instance has a numeric id which can be used to query and modify its properties.

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

import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/index.js';


const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/assets'
};


CreativeEngine.init(config).then(async (engine) => {
  document.getElementById('cesdk_container').append(engine.element);


  const scene = engine.scene.create();


  const page = engine.block.create('page');
  engine.block.setWidth(page, 800);
  engine.block.setHeight(page, 600);
  engine.block.appendChild(scene, page);


  engine.scene.zoomToBlock(page, 40, 40, 40, 40);


  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  const imageFill = engine.block.createFill('image');
  engine.block.setString(
    imageFill,
    'fill/image/imageFileURI',
    'https://img.ly/static/ubq_samples/sample_1.jpg'
  );
  engine.block.setFill(block, imageFill);
  engine.block.setPositionX(block, 100);
  engine.block.setPositionY(block, 50);
  engine.block.setWidth(block, 300);
  engine.block.setHeight(block, 300);
  engine.block.appendChild(page, block);

Accessing Effects

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

engine.block.supportsEffects(scene); // Returns false
engine.block.supportsEffects(block); // Returns true

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 API Docs for a complete list of supported effect types.

const pixelize = engine.block.createEffect('pixelize');
const adjustments = engine.block.createEffect('adjustments');

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.

engine.block.appendEffect(block, pixelize);
engine.block.insertEffect(block, adjustments, 0);
// engine.block.removeEffect(rect, 0);

Querying Effects

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

// This will return [adjustments, pixelize]
const effectsList = engine.block.getEffects(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.

const unusedEffect = engine.block.createEffect('half_tone');
engine.block.destroy(unusedEffect);

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.

const allPixelizeProperties = engine.block.findAllProperties(pixelize);
const allAdjustmentProperties = engine.block.findAllProperties(adjustments);

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.

engine.block.setInt(pixelize, 'pixelize/horizontalPixelSize', 20);
engine.block.setFloat(adjustments, 'effect/adjustments/brightness', 0.2);

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.

engine.block.setEffectEnabled(pixelize, false);
engine.block.setEffectEnabled(
  pixelize,
  !engine.block.isEffectEnabled(pixelize)
);

Full Code

Here’s the full code:

import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/index.js';


const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/assets',
};


CreativeEngine.init(config).then(async engine => {
  document.getElementById('cesdk_container').append(engine.element);


  const scene = engine.scene.create();


  const page = engine.block.create('page');
  engine.block.setWidth(page, 800);
  engine.block.setHeight(page, 600);
  engine.block.appendChild(scene, page);


  engine.scene.zoomToBlock(page, 40, 40, 40, 40);


  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  const imageFill = engine.block.createFill('image');
  engine.block.setString(
    imageFill,
    'fill/image/imageFileURI',
    'https://img.ly/static/ubq_samples/sample_1.jpg',
  );
  engine.block.setFill(block, imageFill);
  engine.block.setPositionX(block, 100);
  engine.block.setPositionY(block, 50);
  engine.block.setWidth(block, 300);
  engine.block.setHeight(block, 300);
  engine.block.appendChild(page, block);


  engine.block.supportsEffects(scene); // Returns false
  engine.block.supportsEffects(block); // Returns true


  const pixelize = engine.block.createEffect('pixelize');
  const adjustments = engine.block.createEffect('adjustments');


  engine.block.appendEffect(block, pixelize);
  engine.block.insertEffect(block, adjustments, 0);
  // engine.block.removeEffect(rect, 0);


  // This will return [adjustments, pixelize]
  const effectsList = engine.block.getEffects(block);


  const unusedEffect = engine.block.createEffect('half_tone');
  engine.block.destroy(unusedEffect);


  const allPixelizeProperties = engine.block.findAllProperties(pixelize);
  const allAdjustmentProperties = engine.block.findAllProperties(adjustments);
  engine.block.setInt(pixelize, 'pixelize/horizontalPixelSize', 20);
  engine.block.setFloat(adjustments, 'effect/adjustments/brightness', 0.2);


  engine.block.setEffectEnabled(pixelize, false);
  engine.block.setEffectEnabled(
    pixelize,
    !engine.block.isEffectEnabled(pixelize),
  );
});