Commonly, a scene contains several pages which in turn contain any other blocks such as images and texts. A block (or design block) is the main building unit in CE.SDK. Blocks are organized in a hierarchy through parent-child relationships. A scene is a specialized block that acts as the root of this hierarchy.
At any time, the engine holds only a single scene. Loading or creating a scene will replace the current one.
Interacting With The Scene#
Creating or Using an Existing Scene#
When using the Engine’s API in the context of the CE.SDK editor, there’s already an existing scene.
You can obtain a handle to this scene by calling the SceneAPI’s scene.get(): number
method.
However, when using the Engine on its own you first have to create a scene, e.g. using scene.create(): number
.
See the Creating Scenes guide for more details and options.
let scene = engine.scene.get(); /* In engine only mode we have to create our own scene and page. */ if (!scene) { scene = engine.scene.create();
Next, we need a page to place our blocks on.
The scene automatically arranges its pages either in a vertical (the default) or horizontal layout.
Again in the context of the editor, there’s already an existing page.
To fetch that page call the BlockAPI’s block.findByType(type: ObjectType): number[]
method and use the first element of the returned array.
When only using the engine, you have to create a page yourself and append it to the scene.
To do that create the page using block.create(type: DesignBlockType): number
and append it to the scene with block.appendChild(parent: number, child: number)
.
const page = engine.block.create('page'); engine.block.appendChild(scene, page); } /* Find all pages in our scene. */ const pages = engine.block.findByType('page'); /* Use the first page we found. */ const page = pages[0];
At this point, you should have a handle to an existing scene as well as a handle to its page. Now it gets interesting when we start to add different types of blocks to the scene’s page.
Modifying the Scene#
As an example, we create a graphic block using the BlockAPI’s create()
method
which we already used for creating our page. Then we set a rect shape and an image fill to this newly created block to give it a visual representation.
To see what other kinds of blocks are available see the Block Types in the API Reference.
/* Create an graphic block with an image fill and add it to the scene's page. */const block = engine.block.create('graphic');engine.block.setShape(block, engine.block.createShape('rect'));const imageFill = engine.block.createFill('image');engine.block.setFill(block, imageFill);
We set a property of our newly created image fill by giving it a URL to reference an image file from.
We also make sure the entire image stays visible by setting the block’s content fill mode to 'Contain'
.
To learn more about block properties check out the Block Properties API Reference.
engine.block.setString( imageFill, 'fill/image/imageFileURI', 'https://img.ly/static/ubq_samples/imgly_logo.jpg',);/* The content fill mode 'Contain' ensures the entire image is visible. */engine.block.setEnum(block, 'contentFill/mode', 'Contain');
And finally, for our image to be visible we have to add it to our page using appendChild
.
engine.block.appendChild(page, block);
To frame everything nicely and put it into view we direct the scene’s camera to zoom on our page.
/* Zoom the scene's camera on our page. */engine.scene.zoomToBlock(page);
Full Code#
Here’s the full code snippet for exploring a scene’s contents using the scene
API:
import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.52.0/index.js';
const config = { license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm', userId: 'guides-user', baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.52.0/assets',};
CreativeEngine.init(config).then(engine => { document.getElementById('cesdk_container').append(engine.element); let scene = engine.scene.get(); /* In engine only mode we have to create our own scene and page. */ if (!scene) { scene = engine.scene.create(); const page = engine.block.create('page'); engine.block.appendChild(scene, page); } /* Find all pages in our scene. */ const pages = engine.block.findByType('page'); /* Use the first page we found. */ const page = pages[0];
/* Create an graphic block with an image fill and add it to the scene's page. */ const block = engine.block.create('graphic'); engine.block.setShape(block, engine.block.createShape('rect')); const imageFill = engine.block.createFill('image'); engine.block.setFill(block, imageFill);
engine.block.setString( imageFill, 'fill/image/imageFileURI', 'https://img.ly/static/ubq_samples/imgly_logo.jpg', ); /* The content fill mode 'Contain' ensures the entire image is visible. */ engine.block.setEnum(block, 'contentFill/mode', 'Contain');
engine.block.appendChild(page, block);
/* Zoom the scene's camera on our page. */ engine.scene.zoomToBlock(page);});
Exploring Scene Contents Using The Scene API#
Functions#
getPages(): DesignBlockId[]
Get the sorted list of pages in the scene.
- Returns The sorted list of pages in the scene.
setDesignUnit(designUnit: DesignUnit): void
Converts all values of the current scene into the given design unit.
designUnit
: The new design unit of the scene
getDesignUnit(): DesignUnit
Returns the design unit of the current scene.
- Returns The current design unit.
type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
The unit type in which the page values (size, distances, etc.) are defined.
getCurrentPage(): DesignBlockId | null
Get the current page, i.e., the page of the first selected element if this page is at least 25% visible or, otherwise, the page nearest to the viewport center.
- Returns The current page in the scene or null.
findNearestToViewPortCenterByType(type: DesignBlockType): DesignBlockId[]
Find all blocks with the given type sorted by the distance to viewport center.
type
: The type to search for.- Returns A list of block ids sorted by distance to viewport center.
findNearestToViewPortCenterByKind(kind: string): DesignBlockId[]
Find all blocks with the given kind sorted by the distance to viewport center.
kind
: The kind to search for.- Returns A list of block ids sorted by distance to viewport center.
Full Code#
Here’s the full code for exploring a scene’s contents:
const pages = engine.scene.getPages();const currentPage = engine.scene.getCurrentPage();const nearestPageByType = engine.scene.findNearestToViewPortCenterByType('//ly.img.ubq/page')[0];const nearestImageByKind = engine.scene.findNearestToViewPortCenterByKind('image')[0];
engine.scene.setDesignUnit('Pixel');
/* Now returns 'Pixel' */engine.scene.getDesignUnit();
Exploring Scene Contents Using The Block API#
Learn how to use the CreativeEditor SDK’s CreativeEngine to explore scenes through the block
API.
Functions#
findAll(): DesignBlockId[]
Return all blocks currently known to the engine.
- Returns A list of block ids.
findAllPlaceholders(): DesignBlockId[]
Return all placeholder blocks in the current scene.
- Returns A list of block ids.
findByType(type: ObjectType): DesignBlockId[]
Finds all blocks with the given type.
type
: The type to search for.- Returns A list of block ids.
findByKind(kind: string): DesignBlockId[]
Finds all blocks with the given kind.
kind
: The kind to search for.- Returns A list of block ids.
findByName(name: string): DesignBlockId[]
Finds all blocks with the given name.
name
: The name to search for.- Returns A list of block ids.
Full Code#
Here’s the full code snippet for exploring a scene’s contents using the block
API:
const allIds = engine.block.findAll();const allPlaceholderIds = engine.block.findAllPlaceholders();const allPages = engine.block.findByType('page');const allImageFills = engine.block.findByType('fill/image');const allStarShapes = engine.block.findByType('shape/star');const allHalfToneEffects = try engine.block.findByType('effect/half_tone')const allUniformBlurs = try engine.block.findByType('blur/uniform')const allStickers = engine.block.findByKind('sticker');const ids = engine.block.findByName('someName');