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#

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

TypeScript


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

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

JavaScript


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.

JavaScript


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.

JavaScript


unstable_enableCameraPositionClamping(ids: 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 the blocks axis-aligned bounding box. Without padding, this results in a tight clamp on the block. With padding, the padded part of the blocks is ensured to be visible.

ids: The blocks to 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 screen pixels to the left of the block that scales with the zoom level until five times the initial value.
scaledPaddingTop: Optional padding in screen pixels to the top of the block that scales with the zoom level until five times the initial value.
scaledPaddingRight: Optional padding in screen pixels to the right of the block that scales with the zoom level until five times the initial value.
scaledPaddingBottom: Optional padding in screen pixels to the bottom of the block that scales with the zoom level until five times the initial value.

JavaScript


unstable_disableCameraPositionClamping(blockOrScene?: number | null): void

Disables any previously set position clamping for the current scene.

blockOrScene: Optionally, the scene or a block in the scene for which to query the position clamping.

JavaScript


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.

JavaScript


unstable_enableCameraZoomClamping(ids: 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.

ids: The blocks to 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.

JavaScript


unstable_disableCameraZoomClamping(blockOrScene?: number | null): void

Disables any previously set zoom clamping for the current scene.

blockOrScene: Optionally, the scene or a block for which to query the zoom clamping.

JavaScript


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.

JavaScript


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.

Settings#

See clamp camera settings in the editor settings.


// 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
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(scene);
// Query if zoom auto-fit is enabled for page
engine.scene.isZoomAutoFitEnabled(scene);

// 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.unstable_disableCameraPositionClamping();
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraPositionClampingEnabled();

// 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.unstable_disableCameraZoomClamping();
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraZoomClampingEnabled();

// 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();