Options

import Foundation
import IMGLYEngine
#if canImport(UIKit)
  import UIKit
#endif
#if canImport(AppKit)
  import AppKit
#endif

@MainActor
func exportingBlocks(engine: Engine) async throws {
  try engine.editor.setSettingString("basePath", value: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/assets")
  try await engine.addDefaultAssetSources()
  let sceneUrl =
    URL(string: "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene")!
  try await engine.scene.load(from: sceneUrl)

  /* Export the scene as PDF. */
  let scene = try engine.scene.get()!
  let mimeTypePdf: MIMEType = .pdf
  let sceneBlob = try await engine.block.export(scene, mimeType: mimeTypePdf)

  /* Export a block as PNG image. */
  let block = try engine.block.find(byType: .graphic).first!
  let mimeTypePng: MIMEType = .png
  /* Optionally, the maximum supported export size can be checked before exporting */
  let maxExportSizeInPixels = try engine.editor.getMaxExportSize()
  /* Optionally, the compression level and the target size can be specified. */
  let options = ExportOptions(pngCompressionLevel: 9, targetWidth: 0, targetHeight: 0)
  let blob = try await engine.block.export(block, mimeType: mimeTypePng, options: options)
  /* Convert the blob to UIImage or NSImage. */
  #if os(iOS)
    let exportedBlock = UIImage(data: blob)
  #endif
  #if os(macOS)
    let exportedBlock = NSImage(data: blob)
  #endif
}

Exporting via the block.export endpoint allows fine-grained control of the target format. CE.SDK currently supports exporting scenes, pages, groups, or individual blocks in the PNG, JPEG, WEBP, BINARY and PDF formats. To specify the desired type, just pass in the corresponding mimeType. Pass additional options in a mime-type specific object:

Format	MimeType	Options (Default)
PNG	`image/png`	`pngCompressionLevel (5)` - The compression level is a trade-off between file size and encoding/decoding speed, but doesn’t affect quality. Valid values are `[0-9]` ranging from no to maximum compression.
JPEG	`image/jpeg`	`jpegQuality (0.9)` - Directly influences the resulting files visual quality. Smaller = worse quality, but lower file size. Valid values are `(0-1]`
WEBP	`image/webp`	`webpQuality (1.0)` - Controls the desired output quality. 1.0 results in a special lossless encoding that usually produces smaller file sizes than PNG. Valid values are (0-1], higher means better quality.
BINARY	`application/octet-stream`	No additional options. This type returns the raw image data in RGBA8888 order in a blob.
PDF	`application/pdf`	`exportPdfWithHighCompatibility (true)` - Increase compatibility with different PDF viewers. Images and effects will be rasterized with regard to the scene’s DPI value instead of simply being embedded.
PDF	`application/pdf`	`exportPdfWithUnderlayer (false)` - An underlayer is generated by adding a graphics block behind the existing elements of the shape of the elements on the page.
PDF	`application/pdf`	`underlayerSpotColorName ("")` - The name of the spot color to be used for the underlayer’s fill.
PDF	`application/pdf`	`underlayerOffset (0.0)` - The adjustment in size of the shape of the underlayer.

Certain formats allow additional configuration, e.g. options.jpegQuality controls the output quality level when exporting to JPEG. These format-specific options are ignored when exporting to other formats. You can choose which part of the scene to export by passing in the respective block as the first parameter.

For all formats, an optional targetWidth and targetHeight in pixels can be specified. If used, the block will be rendered large enough, that it fills the target size entirely while maintaining its aspect ratio. The supported export size limit can be queried with editor.getMaxExportSize(), the width and height should not exceed this value.

Export details:

Exporting automatically performs an internal update to resolve the final layout for all blocks.
Only blocks that belong to the scene hierarchy can be exported.
The export will include the block and all child elements in the block hierarchy.
If the exported block itself is rotated it will be exported without rotation.
If a margin is set on the block it will be included.
If an outside stroke is set on the block it will be included except for pages.
Exporting a scene with more than one page may result in transparent areas between the pages, it is recommended to export the individual pages instead.
Exporting as JPEG drops any transparency on the final image and may lead to unexpected results.

let scene = engine.scene.get()!
let page = engine.scene.getCurrentPage()!

let exportOptions = ExportOptions(
  /**
   * The PNG compression level to use, when exporting to PNG.
   * Valid values are 0 to 9, higher means smaller, but slower.
   * Quality is not affected.
   * Ignored for other encodings.
   * The default value is 5.
   */
  pngCompressionLevel: 5,
  /**
   * The JPEG quality to use when encoding to JPEG.
   * Valid values are (0F-1F], higher means better quality.
   * Ignored for other encodings.
   * The default value is 0.9F.
   */
  jpegQuality: 0.9,
  /**
   * The WebP quality to use when encoding to WebP. Valid values are (0-1], higher means better quality.
   * WebP uses a special lossless encoding that usually produces smaller file sizes than PNG.
   * Ignored for other encodings. Defaults to 1.0.
   */
  webpQuality: 1.0,
  /**
   * An optional target width used in conjunction with target height.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   * The default value is 0.
   */
  targetWidth: 0,
  /**
   * An optional target height used in conjunction with target with.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   * The default value is 0.
   */
  targetHeight: 0,
  /**
   * Export the PDF document with a higher compatibility to different PDF viewers.
   * Bitmap images and some effects like gradients will be rasterized with the DPI
   * setting instead of embedding them directly.
   * The default value is true.
   */
  exportPdfWithHighCompatibility: true,
  /**
   * Export the PDF document with an underlayer.
   * An underlayer is generated by adding a graphics block behind the existing elements of the shape of the elements on
   * the page.
   */
  exportPdfWithUnderlayer: false,
  /**
   * The name of the spot color to be used for the underlayer's fill.
   */
  underlayerSpotColorName: "",
  /**
   * The adjustment in size of the shape of the underlayer.
   */
  underlayerOffset: 0.0
)
let blob = try await engine.block.export(
  scene,
  mimeType: MIMEType.png,
  options: exportOptions
)

let colorMaskedBlob = try await engine.block.exportWithColorMask(
  scene,
  mimeType: MIMEType.png,
  maskColorR: 1,
  maskColorG: 0,
  maskColorB: 0,
  options: exportOptions
)

let videoExportOptions = VideoExportOptions(
  /**
   * Determines the encoder feature set and in turn the quality, size and speed of the encoding process.
   * The default value is `.main`.
   */
  h264Profile: .main,
  /**
   * Controls the H.264 encoding level. This relates to parameters used by the encoder such as bit rate,
   * timings and motion vectors. Defined by the spec are levels 1.0 up to 6.2. To arrive at an integer value,
   * the level is multiplied by ten. E.g. to get level 5.2, pass a value of 52.
   * The default value is 52.
   */
  h264Level: 52,
  /**
   * The video bitrate in bits per second. The maximum bitrate is determined by h264Profile and h264Level.
   * If the value is 0, the bitrate is automatically determined by the engine.
   */
  videoBitrate: 0,
  /**
   * The audio bitrate in bits per second. If the value is 0, the bitrate is automatically determined by the engine (128kbps for stereo AAC stream).
   */
  audioBitrate: 0,
  /**
   * The target frame rate of the exported video in Hz.
   * The default value is 30.
   */
  framerate: 30.0,
  /**
   * An optional target width used in conjunction with target height.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetWidth: 1280,
  /**
   * An optional target height used in conjunction with target width.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetHeight: 720
)
let exportTask = Task {
  for try await export in try await engine.block.exportVideo(page,
                                                             mimeType: MIMEType.mp4,
                                                             options: videoExportOptions) {
    switch export {
    case let .progress(renderedFrames, encodedFrames, totalFrames):
      print("Rendered", renderedFrames, "frames and encoded", encodedFrames, "frames out of", totalFrames)
    case let .finished(video: videoData):
      return videoData
    }
  }
  return Blob()
}
let videoBlob = try await exportTask.value

let maxExportSizeInPixels = engine.editor.getMaxExportSize()

let availableMemoryInBytes = engine.editor.getAvailableMemory()

Export a Static Design

func export(_ id: DesignBlockID, mimeType: MIMEType, options: ExportOptions = .init(), onPreExport: @Sendable (_ engine: Worker) async throws -> Void = { _ in }) async throws -> Blob

Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks.

id: The design block element to export.
mimeType: The mime type of the output file.
options: The options for exporting the block type.
onPreExport: The closure to configure the engine before export. Note that the engine parameter of this closure is a separate engine that runs in the background.
Returns: The exported data.

Export with a Color Mask

func exportWithColorMask(_ id: DesignBlockID, mimeType: MIMEType, maskColorR: Float, maskColorG: Float, maskColorB: Float, options: ExportOptions = .init(), onPreExport: @Sendable (_ engine: Worker) async throws -> Void = { _ in }) async throws -> [Blob]

Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks.

id: The design block element to export.
maskColorB: The red mask color component in the range of 0 to 1.
maskColorG: The green mask color component in the range of 0 to 1.
maskColorB: The blue mask color component in the range of 0 to 1.
mimeType: The mime type of the output file.
options: The options for exporting the block type.
onPreExport: The closure to configure the engine before export. Note that the engine parameter of this closure is a separate engine that runs in the background.
Returns: A list of the exported image data and mask data.

Export a Video

Export a page as a video file of the given mime type.

func exportVideo(_ id: DesignBlockID, mimeType: MIMEType = .mp4, options: VideoExportOptions = .init(), onPreExport: @Sendable (_ engine: Worker) async throws -> Void = { _ in }) async throws -> AsyncThrowingStream<VideoExport, Error>

Exports a design block as a video file of the given mime type.

id: The design block element to export. Currently, only page blocks are supported.
mimeType: The mime type of the output video file.
options: The options for exporting the video.
onPreExport: The closure to configure the engine before export. Note that the engine parameter of this closure is a separate engine that runs in the background.
Returns: A stream of video export events that can be used to monitor the progress of the export and to receive the exported video data.

Export Information

Before exporting, the maximum export size and available memory can be queried.

public func getMaxExportSize() throws -> Int

Get the export size limit in pixels on the current device. An export is only possible when both the width and height of the output are below or equal this limit. However, this is only an upper limit as the export might also not be possible due to other reasons, e.g., memory constraints.

Returns: The upper export size limit in pixels or an unlimited size, i.e, the maximum signed 32-bit integer value, if the limit is unknown.

public func getAvailableMemory() throws -> Int64

Get the currently available memory in bytes

Returns: The available memory in bytes.