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 fun get(): DesignBlock?
method.
However, when using the Engine on its own you first have to create a scene, e.g. using fun create(): DesignBlock
.
See the Creating Scenes guide for more details and options.
// In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val 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 fun findByType(blockType: DesignBlockType): List<DesignBlock>
method and use the first element of the returned list.
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 fun fun create(): DesignBlock
and append it to the scene with fun appendChild(parent: DesignBlock, child: DesignBlock)
.
val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) }
// Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first()
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 a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill)
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( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", )
// The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", )
And finally, for our image to be visible we have to add it to our page using appendChild
.
engine.block.appendChild(parent = page, child = 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 interacting with the scene:
import kotlinx.coroutines.*import ly.img.engine.*
fun modifyingScenes( license: String, userId: String,) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100)
// In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) }
// Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first()
// Create a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill)
engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", )
// The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", )
engine.block.appendChild(parent = page, child = block)
// Zoom the scene's camera on our page. engine.scene.zoomToBlock(page)
engine.stop()}
Exploring Scene Contents Using The Scene API#
Learn how to use the CreativeEditor SDK’s CreativeEngine to explore scene contents through the scene
API.
fun getPages(): List<DesignBlock>
Get the sorted list of pages in the scene.
- Returns the sorted list of pages in the scene.
fun getCurrentPage(): DesignBlock?
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.
fun findNearestToViewPortCenterByType(blockType: DesignBlockType): List<DesignBlock>
Finds all blocks with the given type sorted by distance to viewport center.
-
blockType
: the type to search for. -
Returns a list of block ids sorted by distance to viewport center.
fun findNearestToViewPortCenterByKind(blockKind: String): List<DesignBlock>
Finds all blocks with the given kind sorted by distance to viewport center.
-
blockKind
: the kind to search for. -
Returns a list of block ids sorted by distance to viewport center.
fun setDesignUnit(designUnit: DesignUnit)
Converts all values of the current scene into the given design unit.
designUnit
: the new design unit of the scene.
fun getDesignUnit(): DesignUnit
Returns the design unit of the current scene.
- Returns The current design unit.
Full Code#
Here’s the full code snippet for exploring a scene’s contents using the scene
API:
val pages = engine.scene.getPages()val currentPage = engine.scene.getCurrentPage();val nearestPageByType = engine.scene.findNearestToViewPortCenterByType(DesignBlockType.Page).first();val nearestImageByKind = engine.sce.findNearestToViewPortCenterByKind("image").first();
engine.scene.setDesignUnit(DesignUnit.PIXEL)
/* Now returns DesignUnit.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#
fun findAll(): List<DesignBlock>
Return all blocks currently known to the engine.
- Returns a list of block ids.
fun findAllPlaceholders(): List<DesignBlock>
Return all placeholder blocks in the current scene.
- Returns a list of block ids.
fun findByType(type: DesignBlockType): List<DesignBlock>
Finds all design blocks with the given type.
-
type
: the type to search for. -
Returns a list of block ids.
fun findByType(type: ShapeType): List<DesignBlock>
Finds all shape blocks with the given type.
-
type
: the type to search for. -
Returns a list of block ids.
fun findByType(type: EffectType): List<DesignBlock>
Finds all effect blocks with the given type.
-
type
: the type to search for. -
Returns a list of block ids.
fun findByType(type: BlurType): List<DesignBlock>
Finds all blur blocks with the given type.
-
type
: the type to search for. -
Returns a list of block ids.
fun findByKind(blockKind: String): List<DesignBlock>
Finds all blocks with the given kind.
-
blockKind
: the kind to search for. -
Returns a list of block ids.
fun findByName(name: String): List<DesignBlock>
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:
val allIds = engine.block.findAll()val allPlaceholderIds = engine.block.findAllPlaceholders()val allPages = engine.block.findByType(DesignBlockType.Page)val allImageFills = engine.block.findByType(FillType.Image)val allStarShapes = engine.block.findByType(ShapeType.Star)val allHalfToneEffects = engine.block.findByType(EffectType.HalfTone)val allUniformBlurs = engine.block.findByType(BlurType.Uniform)val allStickers = engine.block.findByKind("sticker")val ids = engine.block.findByName("someName")