@cesdk/engine 1.9.0-preview.3 → 1.9.1

package/index.d.ts

@@ -21,6 +21,7 @@ export declare interface Asset {
         uri?: string;
         filename?: string;
         vectorPath?: string;
+        duration?: string;
     } & Record<string, unknown>;
 }
 
@@ -79,6 +80,8 @@ export declare class AssetAPI {
     canManageAssets(sourceId: string): boolean;
 
 
+
+
     /**
      * Apply an asset result to the active scene.
      * The default behavior will instantiate a block and configure it according to the asset's properties.
@@ -87,12 +90,25 @@ export declare class AssetAPI {
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
     apply(sourceId: string, assetResult: AssetResult): Promise<void>;
+    /**
+     * Apply an asset result to the given block.
+     * @param sourceId - The ID of the asset source.
+     * @param assetResult - A single assetResult of a `findAssets` query.
+     * @param block - The block the asset should be applied to.
+     */
+    applyToBlock(sourceId: string, assetResult: AssetResult, block: DesignBlockId): Promise<void>;
     /**
      * The default implementation for applying an asset to the scene.
      * This implementation is used when no `applyAsset` function is provided to `addSource`.
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
     defaultApplyAsset(assetResult: AssetResult): Promise<void>;
+    /**
+     * The default implementation for applying an asset to an existing block.
+     * @param assetResult - A single assetResult of a `findAssets` query.
+     * @param block - The block to apply the asset result to.
+     */
+    defaultApplyAssetToBlock(assetResult: AssetResult, block: DesignBlockId): Promise<void>;
 
 }
 
@@ -192,6 +208,7 @@ declare interface AssetResult_2 {
     meta?: {
         uri?: string;
         filename?: string;
+        duration?: string;
     } & Record<string, unknown>;
     /** The locale of the label and tags */
     locale?: string;
@@ -264,6 +281,11 @@ export declare interface AssetSource {
      * You can override this with custom behavior.
      */
     applyAsset?: (asset: AssetResult) => Promise<void>;
+    /**
+     * Apply the given asset result to the given block.
+     * You can override this with custom behavior.
+     */
+    applyAssetToBlock?: (asset: AssetResult, block: DesignBlockId) => Promise<void>;
     /**
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
@@ -284,6 +306,12 @@ export declare interface AssetSource {
      * @returns true if asset was found and removed, and false otherwise
      */
     removeAsset?(assetId: string): Promise<boolean>;
+    /**
+     * Generates a list of supported mime types for this source.
+     *
+     * @returns a list of the mime types should be supported by this source
+     */
+    getSupportedMimeTypes?(): string[] | undefined;
 }
 
 /**
@@ -298,6 +326,12 @@ declare interface AssetSource_2 {
      * You can override this with custom behavior.
      */
     applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    /**
+     * Apply the given asset result to the given block.
+     * You can override this with custom behavior.
+     */
+    applyAssetToBlock?: (asset: AssetResult_2, block: number) => Promise<void>;
+
     /** Return every available group */
     getGroups?: () => Promise<string[]>;
     /**
@@ -318,6 +352,13 @@ declare interface AssetSource_2 {
         name: string;
         url?: string;
     };
+
+    /**
+     * Generates a list of supported mime types for this source.
+     *
+     * @returns a list of the mime types should be supported by this source
+     */
+    getSupportedMimeTypes?(): string[] | undefined;
 }
 
 /** @public */
@@ -368,18 +409,28 @@ export declare type BlendMode = 'PassThrough' | 'Normal' | 'Darken' | 'Multiply'
 export declare class Block extends Entity {
     #private;
     effects: ReadWriteChannelSync<number[]>;
+    blur: ReadWriteChannelSync<number>;
+    isBlurEnabled: ReadWriteChannelSync<boolean>;
     soloPlaybackEnabled: ReadWriteChannelSync<boolean>;
     trimOffset: ReadWriteChannelSync<number>;
     trimLength: ReadWriteChannelSync<number>;
     playing: ReadWriteChannelSync<boolean>;
     playbackTime: ReadWriteChannelSync<number>;
     selection: ReadWriteChannelSync<boolean>;
-    videoMode: ReadWriteChannelSync<boolean>;
+    sceneMode: ReadWriteChannelSync<SceneMode>;
     duration: ReadWriteChannelSync<number>;
+    totalSceneDuration: ReadWriteChannelSync<number>;
     name: ReadWriteChannelSync<string>;
-    muted: ReadWriteChannelSync<boolean>;
+    audioMuted: ReadWriteChannelSync<boolean>;
+    videoMuted: ReadWriteChannelSync<boolean>;
     avResourceTotalDuration: ReadWriteChannelSync<number>;
     timeOffset: ReadWriteChannelSync<number>;
+    cropTranslationX: ReadWriteChannelSync<number>;
+    cropTranslationY: ReadWriteChannelSync<number>;
+    cropTranslation: ReadWriteChannelSync<Vec2>;
+    width: ReadWriteChannelSync<number>;
+    height: ReadWriteChannelSync<number>;
+    dimensions: ReadWriteChannelSync<Vec2>;
 
 
 }
@@ -411,7 +462,20 @@ export declare class BlockAPI {
      * @returns A promise that resolves with an array of the exported image and mask or is rejected with an error.
      */
     exportWithColorMask(handle: DesignBlockId, mimeType: MimeType_2 | undefined, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>;
-
+    /**
+     * Exports a design block as a video file of the given mime type.
+     * Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
+     * @param block - The design block to export.
+     * @param timeOffset - The time offset in seconds of the scene's timeline from which the video will start.
+     * @param duration - The duration in seconds of the final video.
+     * @param mimeType - The mime type of the output video file.
+     * @param resolutionWidth - The target video width in pixel.
+     * @param resolutionHeight - The target video height in pixel.
+     * @param framerate - The target framerate in Hz.
+     * @param progressCallback - A callback which reports on the progress of the export. It informs the receiver of the current frame index, which currently gets exported and the total frame count.
+     * @returns A promise that resolves with video blob or is rejected with an error.
+     */
+    exportVideo(handle: DesignBlockId, timeOffset: number, duration: number, mimeType: MimeType_2 | undefined, resolutionWidth: number, resolutionHeight: number, framerate: number, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void): Promise<Blob>;
     /**
      * Loads existing blocks from the given string.
      * The blocks are not attached by default and won't be visible until attached to a page or the scene.
@@ -463,6 +527,12 @@ export declare class BlockAPI {
      * @returns An array of block ids.
      */
     findAllSelected(): DesignBlockId[];
+    /**
+     * Subscribe to changes in the current set of selected blocks.
+     * @param callback - This function is called at the end of the engine update if the selection has changed.
+     * @returns A method to unsubscribe.
+     */
+    onSelectionChanged(callback: () => void): () => void;
     /**
      * Confirms that a given set of blocks can be grouped together.
      * @param ids - A non-empty array of block ids.
@@ -926,6 +996,29 @@ export declare class BlockAPI {
      * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
      */
     getColorRGBA(id: DesignBlockId, property: string): RGBA;
+    /**
+     * Set a color property of the given design block to the given value.
+     * @param id - The block whose property should be set.
+     * @param property - The name of the property to set.
+     * @param name - The name of the spot color.
+     * @param tint - The tint factor in the range of 0 to 1.
+     * @returns An empty result on success, an error otherwise.
+     */
+    setColorSpot(id: DesignBlockId, property: string, name: string, tint?: number): void;
+    /**
+     * Get the spot color name of a color property of the given design block.
+     * @param id - The block whose property should be queried.
+     * @param property - The name of the property to query.
+     * @returns A result holding the name of the spot color or an error.
+     */
+    getColorSpotName(id: DesignBlockId, property: string): string;
+    /**
+     * Get the spot color tint factor of a color property of the given design block.
+     * @param id - The block whose property should be queried.
+     * @param property - The name of the property to query.
+     * @returns A result holding the tint factor of the spot color or an error.
+     */
+    getColorSpotTint(id: DesignBlockId, property: string): number;
     /**
      * Set an enum property of the given design block to the given value.
      * @param id - The block whose property should be set.
@@ -1830,17 +1923,28 @@ export declare class BlockAPI {
     /**
      * Generate a thumbnail for the given video fill.
      * @param id - The video fill.
-     * @returns A thumbnail encoded as JPEG with a height of 128px.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the video aspect ratio.
+     * @returns A thumbnail encoded as JPEG.
      */
-    getVideoFillThumbnail(id: DesignBlockId): Promise<Blob>;
+    getVideoFillThumbnail(id: DesignBlockId, thumbnailHeight: number): Promise<Blob>;
     /**
      * Generate a thumbnail atlas for the given video fill.
      * @param id - The video fill.
      * @param numberOfColumns - The number of columns to generate.
      * @param numberOfRows - The number of rows to generate.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the video aspect ratio.
      * @returns A thumbnail atlas of the video as JPEG.
      */
-    getVideoFillThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number): Promise<Blob>;
+    getVideoFillThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number, thumbnailHeight: number): Promise<Blob>;
+    /**
+     * Generate a thumbnail atlas for the given page.
+     * @param id - The page.
+     * @param numberOfColumns - The number of columns to generate.
+     * @param numberOfRows - The number of rows to generate.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the page aspect ratio.
+     * @returns A thumbnail atlas of the composition as JPEG.
+     */
+    getPageThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number, thumbnailHeight: number): Promise<Blob>;
 }
 
 /**
@@ -1989,6 +2093,13 @@ export declare interface Configuration {
      * and always create a webgl1 context.
      */
     forceWebGL1?: boolean;
+    /**
+     * Whether the engine should automatically choose an audio output device or
+     * should not output audio at all.
+     *
+     * If not configured the fallback value is 'auto'.
+     */
+    audioOutput?: 'auto' | 'none';
 }
 
 /**
@@ -2027,16 +2138,15 @@ declare class CreativeEngine {
     /**
      * Initialize a `CreativeEngine` using the given `canvas` element and an optional config.
      * @param config - An optional configuration object.
-     * @param canvas - The canvas to use for drawing. Optional, if no canvas is provided,
-     *                 the engine works with an internal offscreen-canvas.
      * @returns An engine instance.
      */
-    static init(config?: Partial<Configuration>): Promise<CreativeEngine & {
-        readonly element: HTMLCreativeEngineCanvasElement;
-    }>;
-    static init(config: Partial<Configuration> | undefined, canvas: HTMLCanvasElement | OffscreenCanvas): Promise<CreativeEngine & {
+    static init<C extends Partial<Configuration>>(config?: C): Promise<CreativeEngine & (C extends {
+        readonly canvas: any;
+    } ? {
         readonly element: undefined;
-    }>;
+    } : {
+        readonly element: HTMLCreativeEngineCanvasElement;
+    })>;
 }
 export default CreativeEngine;
 
@@ -2069,6 +2179,7 @@ export declare enum DesignBlockType {
     Page = "//ly.img.ubq/page",
     Image = "//ly.img.ubq/image",
     Video = "//ly.img.ubq/video",
+    VideoFill = "//ly.img.ubq/fill/video",
     Audio = "//ly.img.ubq/audio",
     Text = "//ly.img.ubq/text",
     Sticker = "//ly.img.ubq/sticker",
@@ -2129,6 +2240,28 @@ export declare class EditorAPI {
      * @returns The text cursor's y position in screen space.
      */
     getTextCursorPositionInScreenSpaceY(): number;
+    /**
+     * Create a history which consists of an undo/redo stack for editing operations.
+     * There can be multiple. But only one can be active at a time.
+     * @returns The handle of the created history.
+     */
+    createHistory(): HistoryId;
+    /**
+     * Destroy the given history, throws an error if the handle doesn't refer to a history.
+     * @param history - The history to destroy.
+     */
+    destroyHistory(history: HistoryId): void;
+    /**
+     * Mark the given history as active, throws an error if the handle doesn't refer to a history.
+     * All other histories get cleared from the active state. Undo/redo operations only apply to the active history.
+     * @param history - The history to make active.
+     */
+    setActiveHistory(history: HistoryId): void;
+    /**
+     * Get the handle to the currently active history. If there's none it will be created.
+     * @returns History - The handle of the active history.
+     */
+    getActiveHistory(): HistoryId;
     /**
      * Adds a new history state to the stack, if undoable changes were made.
      */
@@ -2153,6 +2286,13 @@ export declare class EditorAPI {
      * @returns True if a redo step is available.
      */
     canRedo(): boolean;
+    /**
+     * Subscribe to changes to the undo/redo history.
+     *
+     * @param callback - This function is called at the end of the engine update, if the undo/redo history has been changed.
+     * @returns A method to unsubscribe
+     */
+    onHistoryUpdated(callback: () => void): () => void;
     /**
      * Subscribe to changes to the editor settings.
      * @param callback - This function is called at the end of the engine update, if the editor settings have changed.
@@ -2274,6 +2414,34 @@ export declare class EditorAPI {
      * @returns `Allow` if the scope is allowed, `Deny` if it is disallowed, and `Defer` if it is deferred to the block-level.
      */
     getGlobalScope(key: string): 'Allow' | 'Deny' | 'Defer';
+    /**
+     * Queries the names of currently set spot colors previously set with `setSpotColorRGB`.
+     * @returns The names of set spot colors.
+     */
+    findAllSpotColors(): string[];
+    /**
+     * Queries the RGB representation set for a spot color.
+     * If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta).
+     * The alpha value is always 1.0.
+     * @param name - The name of a spot color.
+     * @returns A result holding a float array of the four color components.
+     */
+    getSpotColorRGBA(name: string): RGBA;
+    /**
+     * Sets the RGB representation of a spot color.
+     * Use this function to both create a new spot color or update an existing spot color.
+     * @param name - The name of a spot color.
+     * @param r - The red color component in the range of 0 to 1.
+     * @param g - The green color component in the range of 0 to 1.
+     * @param b - The blue color component in the range of 0 to 1.
+     */
+    setSpotColorRGB(name: string, r: number, g: number, b: number): void;
+    /**
+     * Removes a spot color from the list of set spot colors.
+     * @param name - The name of a spot color.
+     * @returns An empty result on success, an error otherwise.
+     */
+    removeSpotColor(name: string): void;
 }
 
 /**
@@ -2404,7 +2572,7 @@ declare type Extensions = {
 /**
  * @public
  */
-export declare type FillType = 'Solid' | 'Gradient';
+export declare type FillType = 'Solid' | 'Gradient' | 'Video';
 
 /** @public */
 declare interface FindAssetsQuery {
@@ -2474,6 +2642,12 @@ declare type Handler<T> = (v: T) => void;
  */
 declare type HexColorString = string;
 
+/**
+ * A numerical identifier for a history stack
+ * @public
+ */
+export declare type HistoryId = number;
+
 /**
  * A wrapper around a plain canvas
  *
@@ -2775,6 +2949,11 @@ export declare class SceneAPI {
      * @returns A Promise that resolves once the template was applied or rejects if there was an error.
      */
     applyTemplateFromURL(url: string): Promise<void>;
+    /**
+     * Get the current scene mode.
+     * @returns The current mode of the scene.
+     */
+    getMode(): SceneMode;
     /**
      * Sets the zoom level of the active scene.
      * Only has an effect if the zoom level is not handled by the UI.
@@ -2807,6 +2986,12 @@ export declare class SceneAPI {
      * @privateRemarks This will currently fire on _all_ changes to camera properties
      */
     onZoomLevelChanged(callback: () => void): () => void;
+    /**
+     * Subscribe to changes to the active scene rendered by the engine.
+     * @param callback - This function is called at the end of the engine update, if the active scene has changed.
+     * @returns A method to unsubscribe.
+     */
+    onActiveChanged(callback: () => void): () => void;
     /**
      * Converts all values of the current scene into the given design unit.
      * @param designUnit - The new design unit of the scene
@@ -2819,9 +3004,32 @@ export declare class SceneAPI {
     unstable_getDesignUnit(): DesignUnit;
 }
 
-/** @public */
+/**
+ * The scene layout determines how the layout stack should layout its pages.
+ * @public
+ */
 export declare type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' | 'DepthStack';
 
+/**
+ * The mode of the scene defines how the editor and playback should behave.
+ * @public
+ */
+export declare type SceneMode = 'Design' | 'Video';
+
+/**
+ * This channel allows to subscribe/update the selected design blocks.
+ * @public
+ */
+export declare class SelectionChannel implements ReadWriteChannelSync<number[]> {
+    #private;
+    subscribe: Source<number[]>;
+
+    private deselectAll;
+    private selectAll;
+    update: (selectedDesignElements: number[]) => void;
+    value: () => number[];
+}
+
 /** @public */
 export declare interface Size2 {
     width: number;
@@ -2855,6 +3063,10 @@ export declare interface SpotColor {
     cmykApproximation: CMYKColor;
 }
 
+declare interface SpotColorLookup {
+    getSpotColorRGBA(name: string): [r: number, g: number, b: number, a: number];
+}
+
 /** @public */
 export declare type StrokeCornerGeometry = 'Bevel' | 'Miter' | 'Round';