@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
317 lines (316 loc) • 10.7 kB
TypeScript
import { Camera, Color, ColorRepresentation, Mesh, Scene, ShaderMaterial, Texture, WebGLRenderer } from "three";
import { Context } from "./engine_setup.js";
import { ICamera } from "./engine_types.js";
import { RGBAColor } from "./js-extensions/index.js";
declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg";
/**
* Take a screenshot from the current scene.
* **NOTE**: Use {@link screenshot2} for more options.
*
* @param context The context to take the screenshot from
* @param width The width of the screenshot
* @param height The height of the screenshot
* @param mimeType The mime type of the image
* @param camera The camera to use for the screenshot
* @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
* @example
* ```ts
* const dataUrl = screenshot();
* saveImage(dataUrl, "screenshot.png");
* ```
*
*/
export declare function screenshot(context?: Context, width?: number, height?: number, mimeType?: ScreenshotImageMimeType, camera?: Camera | null): string | null;
/**
* Options for the {@link screenshot2} function.
*/
export declare type ScreenshotOptions = {
/**
* The context to take the screenshot from. If not provided, the current context will be used.
*/
context?: Pick<Context, "scene" | "renderer" | "mainCamera" | "renderNow" | "updateAspect" | "updateSize" | "currentFrameEvent" | "devicePixelRatio">;
/**
* The width of the screenshot - if not provided, the width of the current renderer will be used.
*/
width?: number;
/**
* The height of the screenshot - if not provided, the height of the current renderer will be used.
*/
height?: number;
/**
* The mime type of the image
*/
mimeType?: ScreenshotImageMimeType;
/**
* The camera to use for the screenshot. If not provided, the main camera of the context will be used.
*/
camera?: Camera | ICamera | null;
/**
* If true, the background will be transparent.
*/
transparent?: boolean;
/**
* If true, the image will be trimmed to the non-transparent area. Has no effect if `transparent` is false.
*/
trim?: boolean;
/**
* The background of the screenshot. If not provided, the currently set background of the renderer/scene will be used
*/
background?: Color | RGBAColor | ColorRepresentation;
/**
* If true onBeforeRender and onAfterRender will be invoked on all renderers in the scene.
* @default true
*/
render_events?: boolean;
};
export declare type ScreenshotOptionsDataUrl = ScreenshotOptions & {
/**
* If set the screenshot will be downloaded using the provided filename.
* NOTE: if you need more control you can manually download the returned image using {@link saveImage}
* @default undefined
*/
download_filename?: string;
};
export declare type ScreenshotOptionsTexture = ScreenshotOptions & {
type: "texture";
/**
* If set the screenshot will be saved to the provided texture.
* @default undefined
*/
target?: Texture;
};
export declare type ScreenshotOptionsBlob = ScreenshotOptions & {
type: "blob";
};
export declare type ScreenshotOptionsShare = ScreenshotOptions & {
/**
* Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
*/
type: "share";
/**
* The filename to use when sharing the screenshot. If not provided, a default filename will be used.
*/
filename?: string;
/**
* The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
*/
file_type?: ScreenshotImageMimeType;
/**
* The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
*/
title?: string;
/**
* The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
*/
text?: string;
/**
* The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
*/
url?: string;
};
declare type ScreenshotOptionsShareReturnType = {
blob: Blob | null;
shared: boolean;
};
/**
* Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.
* @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
* @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
* @category Utilities
* @example
* ```ts
* // 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 });
* ```
*/
export declare function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
/**
* Take a screenshot from the current scene and return a data URL string.
*
* @param opts Screenshot options. All properties are optional.
* @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
* @category Utilities
*
* @example Basic screenshot
* ```ts
* // Take a simple screenshot with default settings
* const dataUrl = screenshot2({});
* console.log(dataUrl); // "data:image/webp;base64,..."
* ```
*
* @example High-resolution screenshot with transparent background
* ```ts
* const dataUrl = screenshot2({
* width: 2048,
* height: 2048,
* mimeType: "image/png",
* transparent: true,
* trim: true, // Remove transparent edges
* });
* ```
*
* @example Screenshot with custom background color
* ```ts
* import { Color } from "three";
*
* const dataUrl = screenshot2({
* width: 1024,
* height: 1024,
* background: new Color(0x00ff00), // Green background
* });
* ```
*
* @example Download screenshot automatically
* ```ts
* screenshot2({
* width: 1920,
* height: 1080,
* mimeType: "image/jpeg",
* download_filename: "my-scene.jpg",
* });
* ```
*
* @example Manual download using saveImage
* ```ts
* const dataUrl = screenshot2({
* width: 1024,
* height: 1024,
* mimeType: "image/webp",
* transparent: true,
* });
* if (dataUrl) {
* saveImage(dataUrl, "screenshot.webp");
* }
* ```
*
* @example Screenshot from specific camera
* ```ts
* const myCamera = this.gameObject.getComponent(Camera);
* const dataUrl = screenshot2({
* camera: myCamera,
* width: 1024,
* height: 1024,
* });
* ```
*/
export declare function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
/**
* Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.
*
* @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.
* @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.
* @category Utilities
*
* @example Upload screenshot to server
* ```ts
* 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)
* ```ts
* 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
* }
* ```
*/
export declare function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
/**
* 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.
*
* @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
* @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
* @category Utilities
*
* @example Share screenshot on mobile
* ```ts
* 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
* ```ts
* 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);
* }
* ```
*/
export declare function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
/** Download a image (must be a data url).
* @param dataUrl The data url of the image
* @param filename The filename of the image
* @example
* ```ts
* const dataUrl = screenshot();
* saveImage(dataUrl, "screenshot.png");
* ```
*/
export declare function saveImage(dataUrl: string | null, filename: string): void;
export declare namespace InternalScreenshotUtils {
/**
* Screenshot rendering for AR
* @param args
* @returns The canvas with the screenshot
*/
export function compositeWithCameraImage(args: {
scene: Scene;
camera: Camera;
renderer: WebGLRenderer;
width: number;
height: number;
}): HTMLCanvasElement;
type FullscreenPlane = Mesh & {
setTexture: (texture: Texture) => void;
};
export function makeFullscreenPlane(options?: {
material?: ShaderMaterial;
defines?: {
[key: string]: boolean | number;
};
}): FullscreenPlane;
export {};
}
export {};