### Install and Initialize curtains.js
Source: https://www.curtainsjs.com/index.html
Installation via npm and basic initialization using the UMD browser script.
```bash
npm i curtainsjs
```
```javascript
import {Curtains, Plane} from 'curtainsjs';
```
```html
```
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
const plane = new Plane(curtains, document.getElementById("my-plane"));
```
--------------------------------
### Texture Options Example
Source: https://www.curtainsjs.com/texture-class.html
Configure texture properties like filtering, anisotropy, wrapping, and alpha blending during creation. Use `curtains.gl` for WebGL constants.
```javascript
const curtains = new Curtains({
container: "canvas"
});
const texture = new Texture(curtains, {
sampler: "uTexture",
premultiplyAlpha: true,
minFilter: curtains.gl.LINEAR_MIPMAP_NEAREST,
anisotropy: 16,
floatingPoint: "half-float"
});
```
--------------------------------
### Chain Quat methods
Source: https://www.curtainsjs.com/quat-class.html
Most Quat methods return the instance, allowing for method chaining. This example sets the axis order and then creates a quaternion from a Vec3.
```javascript
const quaternion = new Quat().setAxisOrder("YXZ").setFromVec3(new Vec3(1, 1, 1));
```
--------------------------------
### Quat Class - Basic Usage and Creation
Source: https://www.curtainsjs.com/quat-class.html
Demonstrates how to create and initialize Quat objects, including default values and chaining methods.
```APIDOC
## Quat Class
Quat is the class used for rotation quaternions manipulations. Quaternions are used to represent rotations in the 3D space.
### Basic Usage
#### Creation
To create a new Quat, just use its constructor. If used without parameters, it will create a quaternion representing a rotation of angle 0 along X, Y and Z axes with "XYZ" as axis order: [0, 0, 0, 1].
```javascript
// create a new Quat quaternion
const quaternion = new Quat();
```
### Use Chaining
Since most of the Quat methods return the quaternion itself, you can use chaining.
```javascript
// create a new Quat quaternion and chain methods
const quaternion = new Quat().setAxisOrder("YXZ").setFromVec3(new Vec3(1, 1, 1));
```
### Parameters
* **elements** (array of floats of length 4, optional) - Values to use for that quaternion. Default to [0, 0, 0, 1].
* **axisOrder** (string, optional) - Axis order to use for the rotation calculations. Default to "XYZ".
```
--------------------------------
### Animating Vertex Z Position
Source: https://www.curtainsjs.com/get-started.html
Example of modifying vertex Z position using a sinusoidal function based on X coordinates and time.
```GLSL
vec3 vertexPosition = aVertexPosition;
vertexPosition.z = sin(vertexPosition.x * 3.141592 + uTime * 0.0375) * 0.05;
gl_Position = uPMatrix * uMVMatrix * vec4(vertexPosition, 1.0);
```
--------------------------------
### TextureLoader Creation and Usage
Source: https://www.curtainsjs.com/texture-loader-class.html
Demonstrates how to create a TextureLoader instance and use it to load an image, with options for texture parameters and callbacks for success or error.
```APIDOC
## TextureLoader Creation and Usage
### Description
Instantiate a TextureLoader to preload images and create textures. This is useful for loading all website textures to the GPU before initializing other components, such as Planes or ShaderPasses.
### Method
`new TextureLoader(curtains)`
### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None
### Request Example
```javascript
// Initialize Curtains
const curtains = new Curtains({ container: "canvas" });
// Create a new TextureLoader instance
const loader = new TextureLoader(curtains);
// Prepare an image element
const image = new Image();
image.crossOrigin = "anonymous";
image.src = "path/to/my-image.jpg";
// Load the image using the TextureLoader
loader.loadImage(image, {
// Texture options
sampler: "uTexture"
}, (texture) => {
// Success callback: texture is ready to use
console.log("Texture loaded successfully:", texture);
}, (image, error) => {
// Error callback: handle loading errors
console.error("Error loading image:", error);
});
```
### Response
#### Success Response (Texture Object)
- **texture** (object): The created texture object, ready to be used.
#### Response Example
```json
{
"texture": { ... } // Texture object details
}
```
### Error Handling
Errors during image loading are handled by the provided error callback function.
```
--------------------------------
### ShaderPass Initialization
Source: https://www.curtainsjs.com/shader-pass-class.html
Configuration parameters for creating a new ShaderPass instance.
```APIDOC
## ShaderPass Initialization
### Description
Defines the parameters used to initialize a ShaderPass object.
### Parameters
#### Request Body
- **curtains** (Curtains class object) - Required - Your Curtains class object.
- **params** (object) - Optional - An object containing the plane parameters:
- **vertexShader** (string) - Optional - Your vertex shader as a string.
- **vertexShaderID** (string) - Optional - The vertex shader ID.
- **fragmentShader** (string) - Optional - Your fragment shader as a string.
- **fragmentShaderID** (string) - Optional - The fragment shader ID.
- **renderOrder** (int) - Optional - Defines in which order the shader passes are drawn. Default to 0.
- **depthTest** (bool) - Optional - If your shader pass should enable or disable the depth test. Default to true.
- **depth** (bool) - Optional - Whether the shader pass render target should use a depth buffer. Default to false.
- **clear** (bool) - Optional - Whether the shader pass render target content should be cleared. Default to true.
- **renderTarget** (RenderTarget class object) - Optional - An already existing render target to use.
- **texturesOptions** (object) - Optional - Default options to apply to the textures.
- **crossOrigin** (string) - Optional - Defines the crossOrigin process to load images.
- **uniforms** (object) - Optional - The uniforms that will be passed to the shaders.
```
--------------------------------
### Initialize a Plane with parameters
Source: https://www.curtainsjs.com/plane-class.html
Configure a Plane with custom shaders and uniforms by passing a parameters object as the third argument.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
const planeElement = document.getElementById("my-plane");
const params = {
vertexShaderID: "my-plane-vs", // ID of your vertex shader script tag
fragmentShaderID: "my-plane-fs", // ID of your fragment shader script tag
uniforms: { // uniforms are what will allow you to interact with your plane
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0, // initial value of the uniform
},
},
};
// create our plane with the above parameters
const plane = new Plane(curtains, planeElement, params);
```
--------------------------------
### Vec2 Class - Basic Usage and Creation
Source: https://www.curtainsjs.com/vec-2-class.html
Demonstrates how to create Vec2 instances, including a null vector and a vector with initial values. It also shows the chaining capability of Vec2 methods.
```APIDOC
## Vec2 Class - Basic Usage and Creation
### Description
This section covers the fundamental usage of the Vec2 class, including its instantiation and the concept of method chaining.
### Creation
To create a new Vec2, use its constructor. If no parameters are provided, it defaults to a null vector (X and Y components equal to 0).
```javascript
// Create a null vector
const nullVector = new Vec2();
// Create a vector with initial values
const vector = new Vec2(1, 1);
```
### Chaining Methods
Most Vec2 methods return the vector instance itself, allowing for method chaining to perform multiple operations sequentially.
```javascript
// Create a new Vec2 vector and chain methods
const chainedVector = new Vec2().addScalar(2).normalize();
```
### onChange Callback
The Vec2 class supports an `onChange` callback that executes whenever a vector component (x or y) is modified. This is achieved using getters and setters.
```javascript
// Create a new Vec2 vector and listen to its changes
const vectorWithCallback = new Vec2().onChange(() => {
console.log('Vector component changed!');
});
// This will trigger the onChange callback
vectorWithCallback.x = 1;
// This will also trigger the onChange callback
vectorWithCallback.y = 2;
```
### Parameters
* **X** (float, optional): Value along the X axis. Defaults to 0.
* **Y** (float, optional): Value along the Y axis. Defaults to 0.
```
--------------------------------
### Create a PingPongPlane instance
Source: https://www.curtainsjs.com/ping-pong-plane-class.html
Initializes a new PingPongPlane and sets up a display plane to render the resulting texture.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
const pingPongPlaneElement = document.getElementById("my-ping-pong-plane");
const params = {
vertexShaderID: "ping-pong-vs", // ID of your vertex shader script tag
fragmentShaderID: "ping-pong-fs", // ID of your fragment shader script tag
sampler: "uTexture", // sampler to use in your fragment shader. Default to "uPingPongTexture"
uniforms: { // uniforms are what will allow you to interact with your plane
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0, // initial value of the uniform
},
},
};
// create our ping pong plane with the above parameters
const pingPongPlane = new PingPongPlane(curtains, pingPongPlaneElement, params);
// create a plane to use our ping pong plane effect
const planeElement = document.getElementById("my-plane");
const plane = new Plane(curtains, planeElement);
// create a texture that will contain the result of our ping pong effect
const pingPongTexture = plane.createTexture({
sampler: "uTexture",
fromTexture: pingPongPlane.getTexture()
});
```
--------------------------------
### CurtainsJS Methods
Source: https://www.curtainsjs.com/curtains-class.html
Methods for initializing and managing the CurtainsJS instance.
```APIDOC
## setPixelRatio
### Description
Sets a new pixel ratio and resizes the canvas accordingly. Useful for performance optimization by limiting the pixel ratio.
### Method
`setPixelRatio(pixelRatio, triggerCallback)`
### Parameters
#### Parameters
- **pixelRatio** (float) - The new pixel ratio to set.
- **triggerCallback** (bool, optional) - Whether to trigger the onAfterResize callback. Defaults to false.
### Request Example
```javascript
curtains.setPixelRatio(1.5, true);
```
## updateScrollValues
### Description
Updates the scroll values. Should be called before updating plane positions when scrolling.
### Method
`updateScrollValues(xOffset, yOffset)`
### Parameters
#### Parameters
- **xOffset** (float) - Scroll value along the X axis.
- **yOffset** (float) - Scroll value along the Y axis.
### Request Example
```javascript
curtains.updateScrollValues(window.scrollX, window.scrollY);
```
```
--------------------------------
### Constructor: new Curtains()
Source: https://www.curtainsjs.com/curtains-class.html
Initializes a new Curtains instance to manage the WebGL scene.
```APIDOC
## Constructor: new Curtains()
### Description
Creates a new Curtains object that handles the scene, WebGL context, canvas creation, and the requestAnimationFrame loop.
### Parameters
#### Request Body
- **container** (HTML Element or string) - Optional - The HTML Element or ID of the element that will wrap the canvas.
- **alpha** (bool) - Optional - Whether the WebGL context should handle transparency. Default: true.
- **antialias** (bool) - Optional - Whether the WebGL context should use default antialiasing. Default: true.
- **premultipliedAlpha** (bool) - Optional - Whether the WebGL context should handle premultiplied alpha. Default: false.
- **depth** (bool) - Optional - Whether the WebGL context should handle depth. Default: true.
- **preserveDrawingBuffer** (bool) - Optional - Whether the WebGL context should preserve the drawing buffer. Default: false.
- **failIfMajorPerformanceCaveat** (bool) - Optional - Whether the WebGL context creation should fail in case of major performance caveat. Default: true.
- **stencil** (bool) - Optional - Whether the WebGL context should handle stencil. Default: false.
- **autoRender** (bool) - Optional - Whether the library should create a request animation frame loop. Default: true.
- **autoResize** (bool) - Optional - Whether the library should listen to window resize events. Default: true.
- **pixelRatio** (float) - Optional - Defines the pixel ratio value. Default: window.devicePixelRatio.
- **renderingScale** (float) - Optional - Downscale the rendering canvas (0.25 to 1). Default: 1.
- **watchScroll** (bool) - Optional - Whether the library should listen to window scroll events. Default: true.
- **production** (bool) - Optional - Whether the library should throw useful console warnings. Default: false.
### Request Example
const curtains = new Curtains({
container: "canvas",
production: true
});
```
--------------------------------
### Create a basic ShaderPass
Source: https://www.curtainsjs.com/shader-pass-class.html
Initialize a ShaderPass applied to the entire scene using the Curtains object.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
// create a new shader pass using our curtains object
const shaderPass = new ShaderPass(curtains);
```
--------------------------------
### JavaScript Initialization
Source: https://www.curtainsjs.com/get-started.html
Initializes the WebGL context and creates a plane with custom uniforms.
```javascript
import {Curtains, Plane} from "curtainsjs";
// wait for everything to be ready
window.addEventListener("load", () => {
// set up our WebGL context and append the canvas to our wrapper
const curtains = new Curtains({
container: "canvas"
});
// get our plane element
const planeElement = document.getElementsByClassName("plane")[0];
// set our initial parameters (basic uniforms)
const params = {
vertexShaderID: "plane-vs", // our vertex shader ID
fragmentShaderID: "plane-fs", // our fragment shader ID
uniforms: {
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0,
},
},
};
// create our plane using our curtains object, the HTML element and the parameters
const plane = new Plane(curtains, planeElement, params);
plane.onRender(() => {
// use the onRender method of our plane fired at each requestAnimationFrame call
plane.uniforms.time.value++; // update our time uniform value
});
});
```
--------------------------------
### Configure ShaderPass with parameters
Source: https://www.curtainsjs.com/shader-pass-class.html
Define custom shaders and uniforms for a ShaderPass during initialization.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
const shaderPassParams = {
vertexShaderID: "my-shader-pass-vs", // ID of your vertex shader script tag
fragmentShaderID: "my-shader-pass-fs", // ID of your fragment shader script tag
uniforms: { // uniforms are what will allow you to interact with your shader pass
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0, // initial value of the uniform
},
},
};
// create a new shader pass using our curtains object and the above parameters
var shaderPass = new ShaderPass(curtains, shaderPassParams);
```
--------------------------------
### Vec3 Class - Basic Usage
Source: https://www.curtainsjs.com/vec-3-class.html
Demonstrates the creation and basic usage patterns of the Vec3 class, including constructor usage, chaining methods, and setting up an onChange callback for component changes.
```APIDOC
## Vec3 Class - Basic Usage
### Description
Vec3 is the class used for all 3 dimensions vector manipulations.
### Creation
To create a new Vec3, just use its constructor. If used without parameters, it will create a null vector Vec3 with X, Y and Z components equal to 0.
### Chaining
Since most of the Vec3 methods return the vector itself, you can use chaining.
### onChange Callback
Vec3 class is using getters and setters, allowing to execute a function each time one of the vector components changes.
### Code Examples
```javascript
// create two new Vec3 vectors
const nullVector = new Vec3();
const vector = new Vec3(1, 1, 1);
// create a new Vec3 vector and chain methods
const chainedVector = new Vec3().addScalar(2).normalize();
// create a new Vec3 vector and listen to its changes
const observableVector = new Vec3().onChange(() => {
// one of the vector component just changed, do something...
console.log('Vector component changed!');
});
// this will trigger our onChange callback
observableVector.x = 1;
// be careful, this will trigger onChange again!
observableVector.y = 2;
```
```
--------------------------------
### Plane Initialization Parameters
Source: https://www.curtainsjs.com/plane-class.html
This section outlines the parameters used when creating a new Plane object. These parameters control various aspects of the plane's appearance, behavior, and rendering.
```APIDOC
## POST /api/planes
### Description
Initializes a new Plane object with specified parameters.
### Method
POST
### Endpoint
/api/planes
### Parameters
#### Request Body
- **curtains** (object) - Required - Your Curtains class object.
- **planeElement** (HTMLElement) - Required - The HTML element to be used for the plane.
- **params** (object) - Optional - An object containing various parameters for the plane:
- **vertexShader** (string) - Optional - Your custom vertex shader code.
- **vertexShaderID** (string) - Optional - The ID of a predefined vertex shader.
- **fragmentShader** (string) - Optional - Your custom fragment shader code.
- **fragmentShaderID** (string) - Optional - The ID of a predefined fragment shader.
- **widthSegments** (integer) - Optional - The number of segments along the X axis (default: 1).
- **heightSegments** (integer) - Optional - The number of segments along the Y axis (default: 1).
- **renderOrder** (int) - Optional - The rendering order of the plane (default: 0).
- **depthTest** (boolean) - Optional - Enables or disables depth testing (default: true).
- **transparent** (boolean) - Optional - Handles plane transparency for rendering order (default: false).
- **cullFace** (string) - Optional - Which face of the plane to cull ('back', 'front', or 'none') (default: 'back').
- **alwaysDraw** (boolean) - Optional - Whether to always draw the plane, bypassing frustum culling (default: false).
- **visible** (boolean) - Optional - Whether the plane should be drawn (default: true).
- **drawCheckMargins** (object) - Optional - Additional margins for draw check calculations:
- **top** (float) - Margin for the top side (default: 0).
- **right** (float) - Margin for the right side (default: 0).
- **bottom** (float) - Margin for the bottom side (default: 0).
- **left** (float) - Margin for the left side (default: 0).
- **watchScroll** (boolean) - Optional - Auto-update plane position on scroll (default: false).
- **autoloadSources** (boolean) - Optional - Automatically load sources on initialization (default: true).
- **texturesOptions** (object) - Optional - Default options for plane textures.
- **crossOrigin** (string) - Optional - Cross-origin setting for texture loading (default: 'anonymous').
- **fov** (integer) - Optional - Field of view for perspective (default: 50).
- **uniforms** (object) - Optional - Uniforms to pass to the shaders:
- **name** (string) - Required - The name of the uniform.
- **type** (string) - Required - The type of the uniform.
- **value** (any) - Required - The value of the uniform (type depends on uniform type).
### Request Example
```json
{
"curtains": "yourCurtainsObject",
"planeElement": "yourHTMLElement",
"params": {
"vertexShader": "\n void main() {\n gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n }\n ",
"fragmentShader": "\n void main() {\n gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);\n }\n ",
"widthSegments": 10,
"heightSegments": 10,
"uniforms": [
{
"name": "uTime",
"type": "1f",
"value": 0.0
}
]
}
}
```
### Response
#### Success Response (200)
- **plane** (object) - The newly created Plane object.
#### Response Example
```json
{
"plane": "yourCreatedPlaneObject"
}
```
```
--------------------------------
### Initialize CurtainsJS and Create a Plane
Source: https://www.curtainsjs.com/get-started.html
Sets up the WebGL context, creates a plane element, and defines basic shader parameters with an animated time uniform. Handles canvas texture animation by drawing a rotating rectangle.
```javascript
import {Curtains, Plane} from "curtainsjs";
// wait for everything to be ready
window.addEventListener("load", () => {
// set up our WebGL context and append the canvas to our wrapper
const curtains = new Curtains({
container: "canvas"
});
// get our plane element
const planeElement = document.getElementsByClassName("plane")[0];
// set our initial parameters (basic uniforms)
const params = {
vertexShaderID: "plane-vs", // our vertex shader ID
fragmentShaderID: "plane-fs", // our fragment shader ID
uniforms: {
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0,
},
},
};
// create our plane using our curtains object, the HTML element and the parameters
const plane = new Plane(curtains, planeElement, params);
// our texture canvas
const textureCanvas = document.getElementById("canvas-texture");
const textureCanvasContext = textureCanvas.getContext("2d");
// get our plane dimensions without triggering reflow
const planeBoundingRect = plane.getBoundingRect();
// set the size of our canvas
textureCanvas.width = planeBoundingRect.width;
textureCanvas.height = planeBoundingRect.height;
// use the onRender method of our plane fired at each requestAnimationFrame call
plane.onRender(() => {
plane.uniforms.time.value++; // update our time uniform value
// here we will handle our canvas texture animation
// clear scene
textureCanvasContext.clearRect(0, 0, textureCanvas.width, textureCanvas.height);
// continuously rotate the canvas
textureCanvasContext.translate(textureCanvas.width / 2, textureCanvas.height / 2);
textureCanvasContext.rotate(Math.PI / 360);
textureCanvasContext.translate(-textureCanvas.width / 2, -textureCanvas.height / 2);
// draw a red rectangle
textureCanvasContext.fillStyle = "#ff0000";
textureCanvasContext.fillRect(textureCanvas.width / 2 - textureCanvas.width / 8, textureCanvas.height / 2 - textureCanvas.height / 8, textureCanvas.width / 4, textureCanvas.height / 4);
});
});
```
--------------------------------
### Create and Use TextureLoader
Source: https://www.curtainsjs.com/texture-loader-class.html
Instantiate a TextureLoader with a Curtains object and use its loadImage method to load an image. Provide a callback for success and another for errors. The texture options allow setting properties like the sampler name.
```javascript
const curtains = new Curtains({
container: "canvas"
});
// create a new texture loader
const loader = new TextureLoader(curtains);
// load an image with the loader
const image = new Image();
image.crossOrigin = "anonymous";
image.src = "path/to/my-image.jpg";
loader.loadImage(image, {
// texture options (we're only setting its sampler name here)
sampler: "uTexture"
}, (texture) => {
// texture has been successfully created, you can safely use it
}, (image, error) => {
// there has been an error while loading the image
});
```
--------------------------------
### HTML for Multiple Textures (Image and Videos)
Source: https://www.curtainsjs.com/get-started.html
Combine images and videos as textures by assigning them different 'data-sampler' attributes for distinct uniform names in shaders.
```html
```
--------------------------------
### Plane Lifecycle and Rendering Methods
Source: https://www.curtainsjs.com/plane-class.html
Methods for managing plane lifecycle, rendering targets, and playback.
```APIDOC
## playVideos()
### Description
Automatically starts playback for all plane videos.
## remove()
### Description
Removes the plane from the Curtains object and renderer, deleting all associated textures.
## removeRenderTarget()
### Description
Removes the plane's current render target if one is assigned.
## resetPlane(htmlElement)
### Description
Resets plane transformation values and optionally syncs with a new HTML element.
### Parameters
- **htmlElement** (HTML element) - Optional - New HTML element for size and position syncing.
## setRenderOrder(renderOrder)
### Description
Sets the render order for the plane. Higher numbers render on top of lower numbers.
### Parameters
- **renderOrder** (int) - Optional - The new render order value.
```
--------------------------------
### Quat Class - Methods
Source: https://www.curtainsjs.com/quat-class.html
Documentation for the methods available on Quat objects.
```APIDOC
## Quat Class Methods
### Methods
* **clone**(): v7.2
Clone this quaternion.
**returns:** new cloned quaternion.
* **copy**(quaternion): v7.0
Copy a quaternion into this quaternion.
* **quaternion** (Quat class object) - quaternion to copy
**returns:** this quaternion after copy.
* **equals**(quaternion): v7.0
Checks if 2 quaternions are equal (i.e. have the same values and axis orders).
* **quaternion** (Quat class object) - quaternion to compare
**returns:** true if the 2 quaternions are equals, false otherwise.
* **setAxisOrder**(axisOrder): v7.0
Sets the quaternion values from an array.
* **axisOrder** (string) - a string representing the axis order to use. Could be "XYZ", "YXZ", "ZXY", "ZYX", "YZX" or "XZY".
**returns:** this quaternion after axis order has been set.
* **setFromArray**(array): v7.0
Sets the quaternion values from an array.
* **array** (array) - an array of at least 4 floats
**returns:** this quaternion after being set.
* **setFromVec3**(vector): v7.0
Sets a rotation quaternion using Euler angles as a Vec3 and its axis order.
* **vector** (Vec3 class object) - rotation vector to set our quaternion from
**returns:** this quaternion after having applied the rotation.
```
--------------------------------
### Initialize Curtains Object
Source: https://www.curtainsjs.com/curtains-class.html
Create a Curtains instance by passing a container element or ID. The production flag can be set to true to disable console warnings.
```javascript
const curtains = new Curtains({
container: document.getElementById("canvas") // we could have just pass "canvas" instead
});
```
```javascript
const curtains = new Curtains({
container: "canvas",
production: true // use the library in "production" mode
});
```
--------------------------------
### JavaScript Initialization and Video Playback Control
Source: https://www.curtainsjs.com/get-started.html
Initialize CurtainsJS, create a Plane, and set up an event listener to play videos on user interaction. Videos may require user gesture to autoplay on mobile.
```javascript
import {Curtains, Plane} from "curtainsjs";
// wait for everything to be ready
window.addEventListener("load", () => {
// set up our WebGL context and append the canvas to our wrapper
const curtains = new Curtains({
container: "canvas"
});
// get our plane element
const planeElement = document.getElementsByClassName("plane")[0];
// set our initial parameters (basic uniforms)
const params = {
vertexShaderID: "plane-vs", // our vertex shader ID
fragmentShaderID: "plane-fs", // our fragment shader ID
uniforms: {
time: {
name: "uTime", // uniform name that will be passed to our shaders
type: "1f", // this means our uniform is a float
value: 0,
},
},
};
// create our plane using our curtains object, the HTML element and the parameters
const plane = new Plane(curtains, planeElement, params);
plane.onReady(() => {
// set an event listener to start our playback
document.getElementbyId("start-playing").addEventListener("click", () => {
plane.playVideos();
});
}).onRender(() => {
// use the onRender method of our plane fired at each requestAnimationFrame call
plane.uniforms.time.value++; // update our time uniform value
});
});
```
--------------------------------
### Context and Lifecycle Management
Source: https://www.curtainsjs.com/curtains-class.html
Methods for handling the WebGL context and container lifecycle.
```APIDOC
## dispose()
### Description
Cancels the requestAnimationFrame loop, removes all planes, and deletes the WebGL context.
## isWebGL2()
### Description
Checks whether the created WebGL context is using WebGL2.
### Returns
- **isWebGL2** (boolean) - True if using WebGL2.
## restoreContext()
### Description
Attempts to restore the WebGL context after it has been lost.
## setContainer(container)
### Description
Sets the HTML container element to which the canvas will be appended.
### Parameters
#### Request Body
- **container** (HTMLElement) - Required - The container element.
```
--------------------------------
### Initialize a basic Plane
Source: https://www.curtainsjs.com/plane-class.html
Create a new Plane instance by passing the curtains object and the target HTML element.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
const planeElement = document.getElementById("my-plane");
const plane = new Plane(curtains, planeElement);
```
--------------------------------
### Create a RenderTarget
Source: https://www.curtainsjs.com/render-target-class.html
Instantiate a RenderTarget object. Ensure the Curtains instance is initialized with a container element.
```javascript
const curtains = new Curtains({
container: "canvas"
});
const renderTarget = new RenderTarget(curtains);
```
--------------------------------
### Constructor: new Plane(curtains, planeElement, params)
Source: https://www.curtainsjs.com/plane-class.html
Initializes a new WebGL plane linked to an HTML element with optional shader and uniform configurations.
```APIDOC
## Constructor: new Plane(curtains, planeElement, params)
### Description
Creates a new Plane instance. The plane is automatically sized and positioned based on the provided HTML element.
### Parameters
- **curtains** (Curtains) - Required - The Curtains object instance.
- **planeElement** (HTMLElement) - Required - The HTML element to associate with the plane.
- **params** (Object) - Optional - Configuration object for shaders and uniforms.
#### Params Object
- **vertexShaderID** (string) - Optional - ID of the vertex shader script tag.
- **fragmentShaderID** (string) - Optional - ID of the fragment shader script tag.
- **uniforms** (Object) - Optional - Definitions for shader uniforms.
### Request Example
```javascript
const params = {
vertexShaderID: "my-plane-vs",
fragmentShaderID: "my-plane-fs",
uniforms: {
time: {
name: "uTime",
type: "1f",
value: 0
}
}
};
const plane = new Plane(curtains, planeElement, params);
```
```
--------------------------------
### Create a Mat4 instance
Source: https://www.curtainsjs.com/mat-4-class.html
Instantiate a new 4-dimensional identity matrix.
```javascript
// create a new Mat4 identity matrix
const matrix = new Mat4();
```
--------------------------------
### Create Texture using Constructor
Source: https://www.curtainsjs.com/texture-class.html
Instantiate a new Texture object directly using the Curtains constructor. This is the most straightforward method for texture creation.
```javascript
const curtains = new Curtains({
container: "canvas"
});
const texture = new Texture(curtains, {
sampler: "uTexture"
});
```
--------------------------------
### FXAAPass Constructor
Source: https://www.curtainsjs.com/fxaa-pass-class.html
Demonstrates the basic usage of the FXAAPass constructor to add anti-aliasing to your scene.
```APIDOC
## FXAAPass Constructor
### Description
Instantiates a new FXAAPass object to apply Fast Approximate Anti-Aliasing to the scene.
### Method
`new FXAAPass(curtains, options)`
### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
- **curtains** (Curtains) - Required - The Curtains object instance.
- **options** (Object) - Optional - An object to configure ShaderPass parameters. Available options include: **clear**, **depth**, **depthTest**, **renderOrder**, **renderTarget**, **texturesOptions**.
### Request Example
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
// create our FXAA pass using our curtains object
const fxaaPass = new FXAAPass(curtains);
// Example with options:
const fxaaPassWithOptions = new FXAAPass(curtains, {
depthTest: false,
renderOrder: 1
});
```
### Response
#### Success Response (200)
None (This is a constructor)
#### Response Example
None
```
--------------------------------
### Utility and Math Methods
Source: https://www.curtainsjs.com/curtains-class.html
Helper methods for calculations and scene updates.
```APIDOC
## lerp(start, end, amount)
### Description
Calculates a linear interpolation between start and end values.
### Parameters
#### Request Body
- **start** (float) - Required - Starting value
- **end** (float) - Required - Ending value
- **amount** (float) - Required - Interpolation amount
### Returns
- **result** (float) - The interpolated value.
## nextRender(callback, keep)
### Description
Executes a function on the next render call.
### Parameters
#### Request Body
- **callback** (function) - Required - Function to execute
- **keep** (bool) - Optional - Whether to keep executing the callback (default: false).
```
--------------------------------
### Constructor: new RenderTarget(curtains, params)
Source: https://www.curtainsjs.com/render-target-class.html
Creates a new RenderTarget instance associated with a Curtains object.
```APIDOC
## Constructor: new RenderTarget(curtains, params)
### Description
Initializes a new RenderTarget to create a Frame Buffer Object (FBO).
### Parameters
#### Request Body
- **curtains** (Curtains object) - Required - The Curtains class object.
- **params** (object) - Optional - Configuration object for the render target.
- **depth** (bool) - Optional - Whether to create a depth buffer. Default: false.
- **clear** (bool) - Optional - Whether to clear the render target before drawing. Default: true.
- **maxWidth** (float) - Optional - Maximum width of the render target.
- **maxHeight** (float) - Optional - Maximum height of the render target.
- **minWidth** (float) - Optional - Minimum width of the render target. Default: 1024.
- **minHeight** (float) - Optional - Minimum height of the render target. Default: 1024.
- **texturesOptions** (object) - Optional - Default options for the render target texture.
### Request Example
const renderTarget = new RenderTarget(curtains, {
depth: false,
clear: true
});
```
--------------------------------
### loadVideo
Source: https://www.curtainsjs.com/texture-loader-class.html
Loads a single video element or source URL and creates a texture.
```APIDOC
## loadVideo(videoElement, textureOptions, successCallback, errorCallback)
### Description
Takes a video HTML element or source URL and creates a Texture using it.
### Parameters
- **videoElement** (HTMLVideoElement|string) - Required - A HTML video element or video source URL to load.
- **textureOptions** (object) - Optional - Default options to apply to that texture.
- **successCallback** (function) - Optional - Callback executed on successful source load. Receives the newly created texture.
- **errorCallback** (function) - Optional - Callback executed on source load error. Receives the video element and the error object.
```
--------------------------------
### loadVideos
Source: https://www.curtainsjs.com/texture-loader-class.html
Loads an array of video elements or source URLs and creates a texture for each.
```APIDOC
## loadVideos(videoElements, texturesOptions, successCallback, errorCallback)
### Description
Takes an array or collection of video HTML elements or source URLs and creates a Texture for each of them.
### Parameters
- **videoElements** (array|collection) - Required - An array or collection of HTML video elements or video source URLs to load.
- **texturesOptions** (object) - Optional - Default options to apply to those textures.
- **successCallback** (function) - Optional - Callback executed on each successful source load. Receives the newly created texture.
- **errorCallback** (function) - Optional - Callback executed on each source load error. Receives the video element and the error object.
```
--------------------------------
### Create Vec3 instances
Source: https://www.curtainsjs.com/vec-3-class.html
Instantiate a new Vec3 object with optional X, Y, and Z components.
```javascript
// create two new Vec3 vectors
const nullVector = new Vec3();
const vector = new Vec3(1, 1, 1);
```
--------------------------------
### Initialize FXAAPass
Source: https://www.curtainsjs.com/fxaa-pass-class.html
Create a new Curtains instance and instantiate the FXAAPass using that object.
```javascript
// "canvas" is the ID of our HTML container element
const curtains = new Curtains({
container: "canvas"
});
// create our FXAA pass using our curtains object
const fxaaPass = new FXAAPass(curtains);
```
--------------------------------
### Vec2 Class - Methods
Source: https://www.curtainsjs.com/vec-2-class.html
Documentation for all available methods in the Vec2 class, including arithmetic operations, cloning, copying, and normalization.
```APIDOC
## Vec2 Class - Methods
### Description
This section details the various methods available for Vec2 objects, enabling a wide range of vector manipulations.
### Methods
* **add**(vector: Vec2): Vec2
Adds another vector to this vector.
* **vector** (Vec2 class object): The vector to add.
**Returns:** This vector after addition.
* **addScalar**(scalar: float): Vec2
Adds a scalar value to this vector.
* **scalar** (float): The number to add.
**Returns:** This vector after addition.
* **clone**(): Vec2
Creates a deep copy of this vector.
**Returns:** A new, cloned vector.
* **copy**(vector: Vec2): Vec2
Copies the components of another vector into this vector.
* **vector** (Vec2 class object): The vector to copy from.
**Returns:** This vector after the copy operation.
* **dot**(vector: Vec2): float
Calculates the dot product between this vector and another vector.
* **vector** (Vec2 class object): The vector to use for the dot product calculation.
**Returns:** A float representing the dot product.
* **equals**(vector: Vec2): boolean
Checks if this vector is component-wise equal to another vector.
* **vector** (Vec2 class object): The vector to compare against.
**Returns:** `true` if the vectors are equal, `false` otherwise.
* **max**(vector: Vec2): Vec2
Applies the maximum component-wise values from another vector to this vector.
* **vector** (Vec2 class object): The vector containing the maximum values to apply.
**Returns:** This vector with maximum values applied.
* **min**(vector: Vec2): Vec2
Applies the minimum component-wise values from another vector to this vector.
* **vector** (Vec2 class object): The vector containing the minimum values to apply.
**Returns:** This vector with minimum values applied.
* **multiply**(vector: Vec2): Vec2
Multiplies this vector by another vector component-wise. (Available from v7.1)
* **vector** (Vec2 class object): The vector to multiply with.
**Returns:** This vector after multiplication.
* **multiplyScalar**(scalar: float): Vec2
Multiplies this vector by a scalar value.
* **scalar** (float): The number to multiply by.
**Returns:** This vector after scalar multiplication.
* **normalize**(): Vec2
Normalizes this vector to have a magnitude of 1.
**Returns:** The normalized vector.
* **sanitizeNaNValuesWith**(vector: Vec2): Vec2
Replaces NaN components in this vector with corresponding components from another vector. Primarily for internal error handling.
* **vector** (Vec2 class object): The vector to use for sanitization if this vector's components are NaN.
**Returns:** The sanitized vector.
* **set**(x: float, y: float): Vec2
Sets the X and Y components of the vector to the specified values.
* **x** (float): The new value for the X component.
* **y** (float): The new value for the Y component.
**Returns:** This vector after its components have been set.
* **sub**(vector: Vec2): Vec2
Subtracts another vector from this vector component-wise.
* **vector** (Vec2 class object): The vector to subtract.
**Returns:** This vector after subtraction.
* **subScalar**(scalar: float): Vec2
Subtracts a scalar value from this vector.
* **scalar** (float): The number to subtract.
**Returns:** This vector after scalar subtraction.
```
--------------------------------
### loadSources
Source: https://www.curtainsjs.com/texture-loader-class.html
Loads an array of source elements (images, canvases, videos) or URLs to create multiple Textures.
```APIDOC
## loadSources
### Description
This function takes an array of source elements (or sources URL) and creates Textures using them.
### Method
`loadSources`
### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
- **sourceElements** (array or collection of either images, canvases or videos HTML elements or strings) - Required - An array of image, canvas or video HTML elements or sources URL to load.
- **textureOptions** (object, optional) - Default options to apply to that texture. See the Texture class parameters.
- **successCallback** (function(texture), optional) - Callback executed on each successful source load.
- **texture** (Texture class object) - Newly created texture. You'll have access to the textures onSourceLoaded and onSourceUploaded callbacks here.
- **errorCallback** (function(source, error), optional) - Callback executed on each source load error.
- **source** (either an image, canvas or video HTML element) - The source you were trying to load.
- **error** (object) - Error thrown.
### Request Example
```javascript
const sources = ['img1.jpg', document.getElementById('myCanvas'), 'video.mp4'];
curtains.loadSources(sources);
```
### Response
#### Success Response (texture)
- **texture** (Texture class object) - The newly created texture object for each source.
#### Response Example
```javascript
function onSuccess(texture) {
console.log('Source texture loaded:', texture);
}
function onError(source, error) {
console.error('Error loading source:', source, error);
}
curtains.loadSources(['img1.jpg', 'video.mp4'], {}, onSuccess, onError);
```
```
--------------------------------
### Texture Events
Source: https://www.curtainsjs.com/texture-class.html
Lifecycle events for texture source loading and GPU uploading.
```APIDOC
## onSourceLoaded(callback)
### Description
This function will be called the first time your texture source has been loaded.
### Parameters
#### Path Parameters
- **callback** (function) - Required - Function to execute.
### Response
- **returns** (Texture) - Your Texture object, allowing it to be chainable.
---
## onSourceUploaded(callback)
### Description
This function will be called the first time your texture source has been uploaded to the GPU.
### Parameters
#### Path Parameters
- **callback** (function) - Required - Function to execute.
### Response
- **returns** (Texture) - Your Texture object, allowing it to be chainable.
```
--------------------------------
### Scene Control Methods
Source: https://www.curtainsjs.com/curtains-class.html
Methods for managing the rendering loop and scene state.
```APIDOC
## clear()
### Description
Clears both WebGL context colors and depth buffers.
## clearColor()
### Description
Clears WebGL context color buffer.
## clearDepth()
### Description
Clears WebGL context depth buffer.
## disableDrawing()
### Description
Prevents the scene from being drawn again (paused state). Useful for static scenes to improve performance.
## enableDrawing()
### Description
Re-enables scene drawing after it has been paused via disableDrawing().
## needRender()
### Description
Re-enables the scene drawing for exactly one frame. Useful for updating uniforms while drawing is disabled.
```