Source Sets

Source sets allow specifying an entire set of sources, each with a different size, that should be used for drawing a block. The appropriate source is then dynamically chosen based on the current drawing size. This allows using the same scene to render a preview on a mobile screen using a small image file and a high-resolution file for print in the backend.

This guide will show you how to specify source sets both for existing blocks and when defining assets.

Explore a full code sample on Stackblitz or view the code on Github.

Drawing#

When an image needs to be drawn, the current drawing size in screen pixels is calculated and the engine looks up the most appropriate source file to draw at that resolution.

If a source set is set, the source with the closest size exceeding the drawing size is used
If no source set is set, the full resolution image is downscaled to a maximum edge length of 4096 (configurable via maxImageSize setting) and drawn to the target area

This also gives more control about up- and downsampling to you, as all intermediate resolutions can be generated using tooling of your choice.

Source sets are also used during export of your designs and will resolve to the best matching asset for the export resolution.

Setup the scene#

We first create a new scene with a new page.

Using a Source Set for an existing Block#

To make use of a source set for an existing image fill, we use the setSourceSet API. This defines a set of sources and specifies height and width for each of these sources. The engine then chooses the appropriate source during drawing. You may query an existing source set using getSourceSet. You can add sources to an existing source set with addImageFileURIToSourceSet.

Using a Source Set in an Asset#

For assets, source sets can be defined in the payload.sourceSet field. This is directly translated to the sourceSet property when applying the asset. The resulting block is configured in the same way as the one described above. The code demonstrates how to add an asset that defines a source set to a local source and how applyAsset handles a populated payload.sourceSet.

Video Source Sets#

Source sets can also be used for video fills. This is done by setting the sourceSet property of the video fill. The engine will then use the source with the closest size exceeding the drawing size.

Thumbnails will use the smallest source if features/matchThumbnailSourceToFill is disabled, which is the default.

For low end devices or scenes with large videos, you can force the preview to always use the smallest source when editing by enabling features/forceLowQualityVideoPreview. On export, the highest quality source is used in any case.


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

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  baseURL: './release/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, 50, 50, 50, 50);

  let block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  const imageFill = engine.block.createFill('image');
  engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', [
    {
      uri: 'https://img.ly/static/ubq_samples/sample_1_512x341.jpg',
      width: 512,
      height: 341
    },
    {
      uri: 'https://img.ly/static/ubq_samples/sample_1_1024x683.jpg',
      width: 1024,
      height: 683
    },
    {
      uri: 'https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg',
      width: 2048,
      height: 1366
    }
  ]);
  engine.block.setFill(block, imageFill);
  console.log(engine.block.getSourceSet(imageFill, 'fill/image/sourceSet'));
  engine.block.appendChild(page, block);

  const assetWithSourceSet = {
    id: 'my-image',
    meta: {
      kind: 'image',
      fillType: '//ly.img.ubq/fill/image'
    },
    payload: {
      sourceSet: [
        {
          uri: 'https://img.ly/static/ubq_samples/sample_1_512x341.jpg',
          width: 512,
          height: 341
        },
        {
          uri: 'https://img.ly/static/ubq_samples/sample_1_1024x683.jpg',
          width: 1024,
          height: 683
        },
        {
          uri: 'https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg',
          width: 2048,
          height: 1366
        }
      ]
    }
  };

  // highlight-asset-source
  await engine.asset.addLocalSource('my-dynamic-images');
  engine.asset.addAssetToSource('my-dynamic-images', assetWithSourceSet);
  // highlight-asset-source

  // highlight-apply-asset
  // Could also acquire the asset using `findAssets` on the source
  const result = await engine.asset.defaultApplyAsset(assetWithSourceSet);
  console.log(
    engine.block.getSourceSet(
      engine.block.getFill(result),
      'fill/image/sourceSet'
    )
  ); // Lists the entries from above again.
  // highlight-apply-asset

  const videoFill = engine.block.createFill('video');
  engine.block.setSourceSet(videoFill, 'fill/video/sourceSet', [
    {
      uri: 'https://img.ly/static/example-assets/sourceset/1x.mp4',
      width: 1920,
      height: 1080
    }
  ]);

  await engine.block.addVideoFileURIToSourceSet(
    videoFill,
    'fill/video/sourceSet',
    'https://img.ly/static/example-assets/sourceset/2x.mp4'
  );
});