Skip to main content
Platform
Language

Scene Lifecycle

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to save scenes through the scene API and export them to PNG.

At any time, the engine holds only a single scene. Loading or creating a scene will replace the current one.

Setup#

This example uses the headless CreativeEngine. 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.

Creating a Scene#

create(sceneLayout?: SceneLayout): DesignBlockId

Create a new design scene, along with its own camera.

  • Returns The scene's handle.
type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' | 'DepthStack'

The scene layout determines how the layout stack should layout its pages.

get(): DesignBlockId | null

Return the currently active scene.

  • Returns The scene or null, if none was created yet.
createVideo(): DesignBlockId

Create a new scene in video mode, along with its own camera.

  • Returns The scene's handle.
getMode(): SceneMode

Get the current scene mode.

  • Returns The current mode of the scene.
type SceneMode = 'Design' | 'Video'

The mode of the scene defines how the editor and playback should behave.

createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayout?: SceneLayout, spacing?: number, spacingInScreenSpace?: boolean): Promise<DesignBlockId>

Loads the given image and creates a scene with a single page showing the image. Fetching the image may take an arbitrary amount of time, so the scene isn't immediately available.

  • url: The image URL.
  • dpi: The scene's DPI.
  • pixelScaleFactor: The display's pixel scale factor.
  • Returns A promise that resolves with the scene ID on success or rejected with an error otherwise.
createFromVideo(url: string): Promise<DesignBlockId>

Loads the given video and creates a scene with a single page showing the video. Fetching the video may take an arbitrary amount of time, so the scene isn't immediately available.

  • url: The video URL.
  • Returns A promise that resolves with the scene ID on success or rejected with an error otherwise.

Loading a Scene#

loadFromString(sceneContent: string): Promise<DesignBlockId>

Load the contents of a scene file.

  • sceneContent: The scene file contents, a base64 string.
  • Returns A handle to the loaded scene.
loadFromURL(url: string): Promise<DesignBlockId>

Load a scene from the URL to the scene file. The scene file will be fetched asynchronously by the engine. This requires continuous render calls on this engines instance.

  • url: The URL of the scene file.
  • Returns scene A promise that resolves once the scene was loaded or rejects with an error otherwise.
loadFromArchiveURL(url: string): Promise<DesignBlockId>

Load a previously archived scene from the URL to the scene file. The scene file will be fetched asynchronously by the engine. This requires continuous render calls on this engines instance.

  • url: The URL of the scene file.
  • Returns scene A promise that resolves once the scene was loaded or rejects with an error otherwise.

Saving a Scene#

saveToString(allowedResourceSchemes?: string[]): Promise<string>

Serializes the current scene into a string. Selection is discarded.

  • Returns A promise that resolves with a string on success or an error on failure.
saveToArchive(): Promise<Blob>

Saves the current scene and all of its referenced assets into an archive. The archive contains all assets, that were accessible when this function was called. Blocks in the archived scene reference assets relative from to the location of the scene file. These references are resolved when loading such a scene via loadSceneFromURL.

  • Returns A promise that resolves with a Blob on success or an error on failure.

Events#

onActiveChanged: (callback: () => void) => (() => void)

Subscribe to changes to the active scene rendered by the engine.

  • callback: This function is called at the end of the engine update, if the active scene has changed.
  • Returns A method to unsubscribe.