Zoom

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to control and observe camera zoom via the scene API.

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.

Functions#

getZoomLevel(): number

Get the zoom level of the scene or for a camera in the scene in unit dpx/dot. A zoom level of 2.0 results in one pixel in the design to be two pixels on the screen.

Returns The zoom level of the block's camera.

setZoomLevel(zoomLevel?: number): void

Set the zoom level of the scene, e.g., for headless versions. This only shows an effect if the zoom level is not handled/overwritten by the UI. Setting a zoom level of 2.0f results in one dot in the design to be two pixels on the screen.

zoomLevel: The new zoom level.

zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>

Sets the zoom and focus to show a block. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block.

id: The block that should be focused on.
paddingLeft: Optional padding in screen pixels to the left of the block.
paddingTop: Optional padding in screen pixels to the top of the block.
paddingRight: Optional padding in screen pixels to the right of the block.
paddingBottom: Optional padding in screen pixels to the bottom of the block.
Returns A promise that resolves once the zoom was set or rejects with an error otherwise.

enableZoomAutoFit(id: DesignBlockId, axis: 'Horizontal' | 'Vertical', paddingBefore?: number, paddingAfter?: number): void

Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. No more than one block per scene can have zoom auto-fit enabled. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

id: The block for which the zoom is adjusted.
axis: The block axis for which the zoom is adjusted.
paddingBefore: Optional padding in screen pixels before the block.
paddingAfter: Optional padding in screen pixels after the block.

enableZoomAutoFit(id: DesignBlockId, axis: 'Both', paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void

Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

id: The block for which the zoom is adjusted.
axis: The block axis for which the zoom is adjusted.
paddingLeft: Optional padding in screen pixels to the left of the block.
paddingTop: Optional padding in screen pixels to the top of the block.
paddingRight: Optional padding in screen pixels to the right of the block.
paddingBottom: Optional padding in screen pixels to the bottom of the block.

type ZoomAutoFitAxis = 'Horizontal' | 'Vertical' | 'Both'

The axis(es) for which to auto-fit.

disableZoomAutoFit(blockOrScene: DesignBlockId): void

Disables any previously set zoom auto-fit.

blockOrScene: The scene or a block in the scene for which to disable zoom auto-fit.

isZoomAutoFitEnabled(blockOrScene: DesignBlockId): boolean

Queries whether zoom auto-fit is enabled.

blockOrScene: The scene or a block in the scene for which to query the zoom auto-fit.
Returns True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false otherwise.

unstable_enableCameraPositionClamping(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number, scaledPaddingLeft?: number, scaledPaddingTop?: number, scaledPaddingRight?: number, scaledPaddingBottom?: number): void

Continually ensures the camera position to be within the width and height of a block's axis-aligned bounding box. Without padding, this results in a tight clamp on the block. With padding, the padded part of the block is ensured to be visible. No more than one block per scene can have camera position clamping enabled.

id: The block for which the camera position is adjusted to, usually, the scene or a page.
paddingLeft: Optional padding in screen pixels to the left of the block.
paddingTop: Optional padding in screen pixels to the top of the block.
paddingRight: Optional padding in screen pixels to the right of the block.
paddingBottom: Optional padding in screen pixels to the bottom of the block.
scaledPaddingLeft: Optional padding in pixels to the left of the block that scales with the zoom level.
scaledPaddingTop: Optional padding in pixels to the top of the block that scales with the zoom level.
scaledPaddingRight: Optional padding in pixels to the right of the block that scales with the zoom level.
scaledPaddingBottom: Optional padding in pixels to the bottom of the block that scales with the zoom level.

unstable_disableCameraPositionClamping(): void

Disables any previously set position clamping for the current scene.

unstable_isCameraPositionClampingEnabled(blockOrScene?: number | null): boolean

Queries whether position clamping is enabled.

blockOrScene: Optionally, the scene or a block in the scene for which to query the position clamping.
Returns True if the given block has position clamping set or the scene contains a block for which position clamping is set, false otherwise.

unstable_enableCameraZoomClamping(id: DesignBlockId, minZoomLimit?: number, maxZoomLimit?: number, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void

Continually ensures the zoom level of the camera in the active scene to be in the given range.

id: The block for which the camera zoom limits are adjusted to, usually, the scene or a page.
minZoomLimit: The minimum zoom level limit when zooming out, unlimited when negative.
maxZoomLimit: The maximum zoom level limit when zooming in, unlimited when negative.
paddingLeft: Optional padding in screen pixels to the left of the block. Only applied when the block is not a camera.
paddingTop: Optional padding in screen pixels to the top of the block. Only applied when the block is not a camera.
paddingRight: Optional padding in screen pixels to the right of the block. Only applied when the block is not a camera.
paddingBottom: Optional padding in screen pixels to the bottom of the block. Only applied when the block is not a camera.

unstable_disableCameraZoomClamping(): void

Disables any previously set zoom clamping for the current scene.

unstable_isCameraZoomClampingEnabled(blockOrScene?: number | null): boolean

Queries whether zoom clamping is enabled.

blockOrScene: Optionally, the scene or a block for which to query the zoom clamping.
Returns True if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise.

onZoomLevelChanged: (callback: () => void) => (() => void)

Subscribe to changes to the zoom level.

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

File:

// Zoom to 100%
engine.scene.setZoomLevel(1.0);

// Zoom to 50%
engine.scene.setZoomLevel(0.5 * engine.scene.getZoomLevel());

// Bring entire scene in view with padding of 20px in all directions
await engine.scene.zoomToBlock(scene, 20.0, 20.0, 20.0, 20.0);

// Follow page with padding of 20px in both directions
engine.scene.enableZoomAutoFit(page, 'Both', 20.0, 20.0, 20.0, 20.0);

// Stop following page
engine.scene.disableZoomAutoFit(page);
// Query if zoom auto-fit is enabled for page
engine.scene.isZoomAutoFitEnabled(page);

// Keep the scene with padding of 10px within the camera
engine.scene.unstable_enableCameraPositionClamping(
  scene,
  10.0,
  10.0,
  10.0,
  10.0,
  0.0,
  0.0,
  0.0,
  0.0
)

engine.scene.disablePositionAutoFit()
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraPositionClampingEnabled(scene)

// Allow zooming from 12.5% to 800% relative to the size of a page
engine.scene.unstable_enableCameraZoomClamping(
  page,
  0.125,
  8.0,
  0.0,
  0.0,
  0.0,
  0.0
)

engine.scene.disableZoomAutoFit()
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraZoomClampingEnabled(scene)

// Get notified when the zoom level changes
const unsubscribeZoomLevelChanged = engine.scene.onZoomLevelChanged(() => {
  const zoomLevel = engine.scene.getZoomLevel();
  console.log('Zoom level is now: ', zoomLevel);
});
unsubscribeZoomLevelChanged();