Size Limits - Electron

Configure size limits to balance quality and performance in CE.SDK applications.

Size Limits example showing CE.SDK with maxImageSize configuration

10 mins

estimated time

CE.SDK processes images and videos client-side, which means size limits depend on the user’s GPU capabilities and available memory. Understanding and configuring these limits helps you build applications that deliver high-quality results while maintaining smooth performance across different devices.

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
import packageJson from './package.json';

class Example implements EditorPlugin {
  name = packageJson.name;
  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }

    await cesdk.addDefaultAssetSources();
    await cesdk.addDemoAssetSources({
      sceneMode: 'Design',
      withUploadAssetSources: true
    });
    await cesdk.createDesignScene();

    const engine = cesdk.engine;
    const page = engine.block.findByType('page')[0];

    // Set page dimensions to match image display size for safe export
    engine.block.setWidth(page, 800);
    engine.block.setHeight(page, 600);

    // Add export image action to navigation bar
    cesdk.ui.insertNavigationBarOrderComponent('last', {
      id: 'ly.img.actions.navigationBar',
      children: ['ly.img.exportImage.navigationBar']
    });

    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';

    // ===== Section 1: Reading Current maxImageSize =====
    // Get the current maxImageSize setting
    const currentMaxSize = engine.editor.getSetting('maxImageSize');
    console.log('Current maxImageSize:', currentMaxSize);
    // Default is 4096 pixels

    // ===== Section 2: Setting Different maxImageSize Values =====
    // Configure maxImageSize for different use cases
    // This must be set BEFORE loading images to ensure they're downscaled

    // Low memory devices (mobile, tablets) - use 2048 for safety
    engine.editor.setSetting('maxImageSize', 2048);

    // High quality (professional workflows, desktop)
    // engine.editor.setSetting('maxImageSize', 8192);

    console.log(
      'Updated maxImageSize:',
      engine.editor.getSetting('maxImageSize')
    );

    // ===== Section 3: Observing Settings Changes =====
    // Subscribe to settings changes to update UI when maxImageSize changes
    engine.editor.onSettingsChanged(() => {
      const newMaxSize = engine.editor.getSetting('maxImageSize');
      console.log('maxImageSize changed to:', newMaxSize);
      // In a real app, update UI here to reflect the new setting
    });

    // The subscription returns an unsubscribe function if you need to clean up later
    // const unsubscribe = engine.editor.onSettingsChanged(() => { ... });
    // unsubscribe(); // Call when no longer needed

    // ===== Section 4: GPU Capability Detection (Web) =====
    // Query GPU max texture size to understand export limits
    const canvas = document.createElement('canvas');
    const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');

    if (gl) {
      const maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
      console.log('GPU Max Texture Size:', maxTextureSize);
      console.log(
        'Safe export dimensions: up to',
        maxTextureSize,
        '×',
        maxTextureSize
      );

      // Most modern GPUs support 4096×4096 to 16384×16384
      // Safe baseline is 4096×4096 for universal compatibility
    }

    // ===== Section 5: Pre-Export Size Validation =====
    // Calculate actual export dimensions including all content
    // Get bounding box of all content to check actual export size
    const allBlocks = engine.block.findByType('//ly.img.ubq/graphic');
    let maxRight = 0;
    let maxBottom = 0;

    allBlocks.forEach((blockId) => {
      const x = engine.block.getPositionX(blockId);
      const y = engine.block.getPositionY(blockId);
      const width = engine.block.getWidth(blockId);
      const height = engine.block.getHeight(blockId);
      maxRight = Math.max(maxRight, x + width);
      maxBottom = Math.max(maxBottom, y + height);
    });

    const exportWidth = Math.max(engine.block.getWidth(page), maxRight);
    const exportHeight = Math.max(engine.block.getHeight(page), maxBottom);

    console.log('Export dimensions:', exportWidth, '×', exportHeight);

    if (gl) {
      const maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
      // Use conservative limit (50% of max) for actual VRAM availability
      const safeTextureSize = Math.floor(maxTextureSize * 0.5);

      if (exportWidth > safeTextureSize || exportHeight > safeTextureSize) {
        cesdk.ui.showNotification({
          type: 'warning',
          message: `Export dimensions (${Math.round(exportWidth)}×${Math.round(exportHeight)}) exceed safe GPU limit (${safeTextureSize}×${safeTextureSize})`
        });
      } else {
        cesdk.ui.showNotification({
          type: 'success',
          message: 'Export dimensions are within safe limits'
        });
      }
    }

    // ===== Section 6: Handling Export Errors =====
    // Demonstrate proper error handling for size-related export failures
    try {
      // Example export operation (not actually exporting in this demo)
      // const blob = await engine.block.export(page, 'image/png');

      // If export fails, catch and handle the error
      console.log('Export would proceed here with proper error handling');
    } catch (error) {
      console.error('Export failed:', error);

      // Check if error is size-related
      if (
        error instanceof Error &&
        (error.message.includes('texture') ||
          error.message.includes('size') ||
          error.message.includes('memory'))
      ) {
        console.error('Size-related export error detected');
        console.error('Suggested remediation:');
        console.error('1. Reduce output dimensions');
        console.error('2. Decrease maxImageSize setting');
        console.error('3. Use export compression options');
      }
    }

    // Add an image to the page for demonstration
    // Note: NOT specifying size here - let maxImageSize control the texture loading
    const imageBlock = await engine.block.addImage(imageUri);
    engine.block.appendChild(page, imageBlock);

    // Fit image to page dimensions
    engine.block.setWidth(imageBlock, 800);
    engine.block.setHeight(imageBlock, 600);

    // Position image to fill the page (already matches page dimensions)
    engine.block.setPositionX(imageBlock, 0);
    engine.block.setPositionY(imageBlock, 0);

    // Zoom to fit the content
    engine.scene.zoomToBlock(page, { padding: 40 });

    // Display information in console
    console.log('=== Size Limits Configuration Summary ===');
    console.log(
      'Current maxImageSize:',
      engine.editor.getSetting('maxImageSize')
    );
    console.log(
      'Page dimensions:',
      engine.block.getWidth(page),
      '×',
      engine.block.getHeight(page)
    );
    console.log(
      'Image dimensions:',
      engine.block.getWidth(imageBlock),
      '×',
      engine.block.getHeight(imageBlock)
    );

    if (gl) {
      const maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
      console.log('GPU max texture size:', maxTextureSize);
    }
  }
}

export default Example;

This guide covers how to configure the maxImageSize setting, query GPU capabilities, validate export dimensions, and handle size-related errors gracefully.

Understanding Size Limits#

CE.SDK manages size limits at two stages: input (when loading images) and output (when exporting). The maxImageSize setting controls input resolution, automatically downscaling images that exceed the configured limit (default: 4096×4096px). This reduces memory usage and improves performance across devices. Export resolution has no artificial limits—the theoretical maximum is 16,384×16,384 pixels, constrained only by GPU texture size, available VRAM, and platform capabilities (WebGL/WebGPU on web, Metal/OpenGL on native).

Resolution & Duration Limits#

Constraint	Recommendation / Limit
Input Resolution	Maximum input resolution is 4096×4096 pixels. Images from external sources (e.g., Unsplash) are resized to this size before rendering on the canvas. You can modify this value using the `maxImageSize` setting.
Output Resolution	There is no enforced output resolution limit. Theoretically, the editor supports output sizes up to 16,384×16,384 pixels. However, practical limits depend on the device’s GPU capabilities and available memory.

All image processing in CE.SDK is handled client-side, so these values depend on the maximum texture size supported by the user’s hardware. The default limit of 4096×4096 is a safe baseline that works universally. Higher resolutions (e.g., 8192×8192) may work on certain devices but could fail on others during export if the GPU texture size is exceeded.

Constraint	Recommendation / Limit
Resolution	Up to 4K UHD is supported for playback and export, depending on the user’s hardware and available GPU resources. For import, CE.SDK does not impose artificial limits, but maximum video size is bounded by the 32-bit address space of WebAssembly (wasm32) and the browser tab’s memory cap (~2 GB).
Frame Rate	30 FPS at 1080p is broadly supported; 60 FPS and high-res exports benefit from hardware acceleration
Duration	Stories and reels of up to 2 minutes are fully supported. Longer videos are also supported, but we generally found a maximum duration of 10 minutes to be a good balance for a smooth editing experience and a pleasant export duration of around one minute on modern hardware.

Configuring maxImageSize#

You can read and modify the maxImageSize setting using the Settings API to match your application’s requirements and target hardware capabilities.

Reading the Current Setting#

To check what maxImageSize value is currently configured:

// Get the current maxImageSize setting
const currentMaxSize = engine.editor.getSetting('maxImageSize');
console.log('Current maxImageSize:', currentMaxSize);
// Default is 4096 pixels

This returns the maximum size in pixels as an integer value (e.g., 4096 for the default 4096×4096 limit). You might display this value in your UI to inform users about the current quality settings, or use it to make runtime decisions about asset loading strategies.

Setting a New Value#

Configure maxImageSize to minimize memory usage on constrained devices:

// Configure maxImageSize for different use cases
// This must be set BEFORE loading images to ensure they're downscaled

// Low memory devices (mobile, tablets) - use 2048 for safety
engine.editor.setSetting('maxImageSize', 2048);

// High quality (professional workflows, desktop)
// engine.editor.setSetting('maxImageSize', 8192);

console.log(
  'Updated maxImageSize:',
  engine.editor.getSetting('maxImageSize')
);

The setting takes effect immediately for newly loaded images. Images already loaded on the canvas retain their current resolution until reloaded.

Observing Settings Changes#

Subscribe to setting changes to update your UI when maxImageSize is modified:

// Subscribe to settings changes to update UI when maxImageSize changes
engine.editor.onSettingsChanged(() => {
  const newMaxSize = engine.editor.getSetting('maxImageSize');
  console.log('maxImageSize changed to:', newMaxSize);
  // In a real app, update UI here to reflect the new setting
});

// The subscription returns an unsubscribe function if you need to clean up later
// const unsubscribe = engine.editor.onSettingsChanged(() => { ... });
// unsubscribe(); // Call when no longer needed

This callback fires whenever any setting changes through the Settings API. You can use it to update quality indicators in your interface, recalculate memory estimates, or trigger asset reloading with the new size limit.

GPU Capability Detection#

Modern browsers expose GPU capabilities through WebGL, allowing you to determine safe export dimensions for the user’s hardware.

// Query GPU max texture size to understand export limits
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');

if (gl) {
  const maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
  console.log('GPU Max Texture Size:', maxTextureSize);
  console.log(
    'Safe export dimensions: up to',
    maxTextureSize,
    '×',
    maxTextureSize
  );

  // Most modern GPUs support 4096×4096 to 16384×16384
  // Safe baseline is 4096×4096 for universal compatibility
}

The MAX_TEXTURE_SIZE parameter returns the maximum width or height (in pixels) for a texture on the current GPU. Most modern GPUs support 4096×4096 to 16384×16384, while older or integrated GPUs may be limited to smaller dimensions.

You can use this information to:

Set conservative maxImageSize defaults based on detected capabilities
Show warnings when users attempt exports that may exceed hardware limits
Provide quality presets that match the device’s capabilities
Calculate safe export dimensions automatically

Troubleshooting#

Common issues and solutions when working with size limits:

Issue	Cause	Solution
Images appear blurry/low quality	`maxImageSize` too low	Increase `maxImageSize` if GPU supports it (query `MAX_TEXTURE_SIZE` first)
Out of memory errors during editing	`maxImageSize` too high	Decrease `maxImageSize` to reduce memory footprint
Export fails with no error message	Output exceeds GPU texture limit	Reduce export dimensions or query `MAX_TEXTURE_SIZE` to set safe maximums
Video export fails	Resolution/duration too high	Export at 1080p instead of 4K, or reduce video duration to under 2 minutes
Inconsistent results across devices	Different GPU capabilities	Set conservative `maxImageSize` (4096) or detect capabilities programmatically
Images load slowly	High `maxImageSize` on slow hardware	Lower `maxImageSize` to reduce processing time, especially on mobile devices
Export succeeds but file is too large	No compression applied	Use JPEG format with quality settings, or apply PNG compression options

API Reference#

Core methods for managing size limits and export operations:

Method	Description
`engine.editor.getSetting()`	Retrieves the current value of a setting
`engine.editor.setSetting()`	Updates a setting value
`engine.editor.onSettingsChanged()`	Subscribes to setting change events
`engine.block.export()`	Exports a block as an image or video
`engine.block.getWidth()`	Gets the width of a block in pixels
`engine.block.getHeight()`	Gets the height of a block in pixels

Next Steps#

Explore related guides to build complete export workflows:

Settings Guide - Complete Settings API reference and configuration options
File Format Support - Supported image and video formats with capabilities
Export Overview - Fundamentals of exporting images and videos from CE.SDK
Export to PDF - PDF export guide with multi-page support and print optimization