Function screenshot2

Take a screenshot from the current scene with advanced options.

This is the main screenshot function in Needle Engine with support for multiple output formats:

  • Data URL (default): Returns a base64-encoded string suitable for img src attributes
  • Texture: Returns a Three.js Texture that can be applied to materials
  • Blob: Returns a Blob for uploading or processing (async)
  • Share: Uses the Web Share API to share the screenshot (async, mobile-friendly)

Param: opts

Screenshot options. Use the type property to specify output format. See ScreenshotOptions for all available options.

Returns

Depending on the type option:

  • Data URL (string) when type is undefined or not specified
  • Texture when type: "texture"
  • Promise<Blob | null> when type: "blob"
  • Promise<{blob, shared}> when type: "share"

Returns null (or Promise resolving to null) if the screenshot could not be taken.

Example: WebXR / AR Screenshots

// Screenshots work automatically in WebXR sessions
// The camera feed will be composited with your 3D content
const dataUrl = screenshot2({
  width: 1920,
  height: 1080
});

Note for AR Screenshots: To include the device camera feed in AR screenshots, you need to request camera access. This is done automatically when you use WebARCameraBackground component in your scene. If you're not using WebARCameraBackground, you can request camera access manually:

export class MyComponent extends Behaviour {
  onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void {
    if (mode === "immersive-ar") {
      args.optionalFeatures = args.optionalFeatures || [];
      args.optionalFeatures.push('camera-access');
    }
  }
}

Without camera access, AR screenshots will only show your 3D content without the real-world background.

Example: Combining multiple options

// High-res transparent screenshot with custom camera
const myCamera = this.gameObject.getComponent(Camera);
const texture = screenshot2({
  type: "texture",
  camera: myCamera,
  width: 2048,
  height: 2048,
  transparent: true,
  trim: true,
  render_events: true, // Ensure reflection probes are updated
});

See

  • screenshot2(opts: ScreenshotOptionsTexture): null | Texture

    Take a screenshot from the current scene and return a Texture. This can be applied to a surface in 3D space.

    Parameters

    • opts: ScreenshotOptionsTexture

      Provide { type: "texture" } to get a texture instead of a data url.

    Returns null | Texture

    The texture of the screenshot. Returns null if the screenshot could not be taken.

    Example

    // Create a texture from the current view
    const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
    if (screenshotTexture) {
      myMaterial.map = screenshotTexture;
      myMaterial.needsUpdate = true;
    }

    // Update an existing texture
    const existingTexture = new Texture();
    screenshot2({ type: "texture", target: existingTexture, transparent: true });
  • screenshot2(opts: ScreenshotOptionsDataUrl): null | string

    Take a screenshot from the current scene and return a data URL string.

    Parameters

    • opts: ScreenshotOptionsDataUrl

      Screenshot options. All properties are optional.

    Returns null | string

    The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.

    Example: Basic screenshot

    // Take a simple screenshot with default settings
    const dataUrl = screenshot2({});
    console.log(dataUrl); // "data:image/webp;base64,..."

    Example: High-resolution screenshot with transparent background

    const dataUrl = screenshot2({
      width: 2048,
      height: 2048,
      mimeType: "image/png",
      transparent: true,
      trim: true, // Remove transparent edges
    });

    Example: Screenshot with custom background color

    import { Color } from "three";

    const dataUrl = screenshot2({
      width: 1024,
      height: 1024,
      background: new Color(0x00ff00), // Green background
    });

    Example: Download screenshot automatically

    screenshot2({
      width: 1920,
      height: 1080,
      mimeType: "image/jpeg",
      download_filename: "my-scene.jpg",
    });

    Example: Manual download using saveImage

    const dataUrl = screenshot2({
      width: 1024,
      height: 1024,
      mimeType: "image/webp",
      transparent: true,
    });
    if (dataUrl) {
      saveImage(dataUrl, "screenshot.webp");
    }

    Example: Screenshot from specific camera

    const myCamera = this.gameObject.getComponent(Camera);
    const dataUrl = screenshot2({
      camera: myCamera,
      width: 1024,
      height: 1024,
    });
  • screenshot2(opts: ScreenshotOptionsBlob): Promise<null | Blob>

    Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.

    Parameters

    • opts: ScreenshotOptionsBlob

      Set { type: "blob" } to get a blob instead of a data url. All other ScreenshotOptions are also available.

    Returns Promise<null | Blob>

    A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.

    Example: Upload screenshot to server

    const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
    if (blob) {
      const formData = new FormData();
      formData.append("screenshot", blob, "screenshot.png");
      await fetch("/api/upload", { method: "POST", body: formData });
    }

    Example: Save blob to file (browser download)

    const blob = await screenshot2({
      type: "blob",
      width: 1920,
      height: 1080,
      transparent: true
    });
    if (blob) {
      const url = URL.createObjectURL(blob);
      saveImage(url, "screenshot.png");
      URL.revokeObjectURL(url); // Clean up
    }
  • screenshot2(
        opts: ScreenshotOptionsShare,
    ): Promise<ScreenshotOptionsShareReturnType>

    Take a screenshot and share it using the Web Share API (mobile-friendly).

    Note: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.

    Parameters

    • opts: ScreenshotOptionsShare

      Set { type: "share" } to share the screenshot. Additional options like filename, title, text, and url can be provided.

    Returns Promise<ScreenshotOptionsShareReturnType>

    A Promise that resolves with an object containing the blob and whether it was successfully shared.

    Example: Share screenshot on mobile

    const result = await screenshot2({
      type: "share",
      filename: "my-creation.png",
      title: "Check out my 3D scene!",
      text: "I created this with Needle Engine",
      url: "https://engine.needle.tools",
      mimeType: "image/png",
    });

    if (result.shared) {
      console.log("Screenshot shared successfully!");
    } else {
      console.log("User cancelled or sharing not supported");
    }

    Example: Share with fallback

    const result = await screenshot2({
      type: "share",
      filename: "screenshot.webp",
      file_type: "image/webp",
    });

    if (!result.shared && result.blob) {
      // Fallback: download the image instead
      const url = URL.createObjectURL(result.blob);
      saveImage(url, "screenshot.webp");
      URL.revokeObjectURL(url);
    }

Settings

Member Visibility