From ce37f248bac66445687b3e5bc9820dacf2a6fa96 Mon Sep 17 00:00:00 2001 From: Tarek Sherif Date: Mon, 14 Oct 2019 17:48:01 -0400 Subject: [PATCH] Remove docs for removed classes --- .../core/lights/ambient-light.md | 27 ---- .../core/lights/directional-light.md | 29 ---- docs/api-reference/core/lights/point-light.md | 34 ----- docs/api-reference/core/material.md | 132 ------------------ docs/api-reference/core/materials/material.md | 65 --------- .../core/materials/pbr-material.md | 77 ---------- .../core/materials/phong-material.md | 31 ---- docs/api-reference/core/multipass/canvas.md | 106 -------------- .../core/multipass/clear-pass.md | 23 --- .../core/multipass/composite-pass.md | 29 ---- .../api-reference/core/multipass/copy-pass.md | 23 --- .../core/multipass/multi-pass-renderer.md | 47 ------- docs/api-reference/core/multipass/pass.md | 22 --- .../core/multipass/render-pass.md | 27 ---- .../core/multipass/shader-module-pass.md | 14 -- .../core/scenegraph/wip/camera-node.md | 25 ---- .../core/scenegraph/wip/mesh-node.md | 39 ------ docs/api-reference/core/shader-cache.md | 51 ------- docs/table-of-contents.json | 37 +---- docs/upgrade-guide.md | 3 + 20 files changed, 4 insertions(+), 837 deletions(-) delete mode 100644 docs/api-reference/core/lights/ambient-light.md delete mode 100644 docs/api-reference/core/lights/directional-light.md delete mode 100644 docs/api-reference/core/lights/point-light.md delete mode 100644 docs/api-reference/core/material.md delete mode 100644 docs/api-reference/core/materials/material.md delete mode 100644 docs/api-reference/core/materials/pbr-material.md delete mode 100644 docs/api-reference/core/materials/phong-material.md delete mode 100644 docs/api-reference/core/multipass/canvas.md delete mode 100644 docs/api-reference/core/multipass/clear-pass.md delete mode 100644 docs/api-reference/core/multipass/composite-pass.md delete mode 100644 docs/api-reference/core/multipass/copy-pass.md delete mode 100644 docs/api-reference/core/multipass/multi-pass-renderer.md delete mode 100644 docs/api-reference/core/multipass/pass.md delete mode 100644 docs/api-reference/core/multipass/render-pass.md delete mode 100644 docs/api-reference/core/multipass/shader-module-pass.md delete mode 100644 docs/api-reference/core/scenegraph/wip/camera-node.md delete mode 100644 docs/api-reference/core/scenegraph/wip/mesh-node.md delete mode 100644 docs/api-reference/core/shader-cache.md diff --git a/docs/api-reference/core/lights/ambient-light.md b/docs/api-reference/core/lights/ambient-light.md deleted file mode 100644 index ecdfe6c4c8..0000000000 --- a/docs/api-reference/core/lights/ambient-light.md +++ /dev/null @@ -1,27 +0,0 @@ -# AmbientLight - -Create an ambient light source which illuminates all the objects equally.Ambient light comes from all directions, adding ambient light ensures that object colors are rendered but does not show structure in 3D objects like directional and point lights do. Only one ambient light is supported. - - -## Usage - -Create an ambient light source with color and intensity. -```js -const ambientLight= new AmbientLight({ - color: [128, 128, 0], - intensity: 2.0 -}); -``` - -## Methods - -### constructor - -The constructor for the `AmbientLight` class. Use this to create a new `AmbientLight`. - -```js -const ambientLight = new AmbientLight({color, intensity}); -``` - -* `color` - (*array*,) RGB color of ambient light source, default value is `[255, 255, 255]`. -* `intensity` - (*number*) Strength of ambient light source, default value is `1.0`. diff --git a/docs/api-reference/core/lights/directional-light.md b/docs/api-reference/core/lights/directional-light.md deleted file mode 100644 index 3cb0a4b648..0000000000 --- a/docs/api-reference/core/lights/directional-light.md +++ /dev/null @@ -1,29 +0,0 @@ -# DirectionalLight - -Create a directional light source which emits from a specific direction.A directional light can be considered "infinitely" far away (like the Sun) and does not attenuate with distance. At most 5 directional lights can be supported. - - -## Usage - -Create a directional light source with color, intensity and direction. -```js -const directionalLight= new DirectionalLight({ - color: [128, 128, 0], - intensity: 2.0, - direction: [0, -100, -100] -}); -``` - -## Methods - -### constructor - -The constructor for the `DirectionalLight` class. Use this to create a new `DirectionalLight`. - -```js -const directionalLight = new DirectionalLight({color, intensity, direction}); -``` - -* `color` - (*array*,) RGB color of directional light source, default value is `[255, 255, 255]`. -* `intensity` - (*number*) Strength of directional light source, default value is `1.0`. -* `direction` - (*array*,) 3D vector specifies the direction the light comes from, default value is `[0, 0, -1]`. diff --git a/docs/api-reference/core/lights/point-light.md b/docs/api-reference/core/lights/point-light.md deleted file mode 100644 index 3688eccb7f..0000000000 --- a/docs/api-reference/core/lights/point-light.md +++ /dev/null @@ -1,34 +0,0 @@ -# PointLight - -Create a point light source which emits from a point in all directions.Point lights attenuation is not available. At most 5 directional lights can be supported. - - -## Usage - -Create a point light source with color, intensity and position. -```js -const pointLight= new PointLight({ - color: [128, 128, 0], - intensity: 2.0, - position: [0, 0, 200] -}); -``` - -## Methods - -### constructor - -The constructor for the `PointLight` class. Use this to create a new `PointLight`. - -```js -const pointLight = new PointLight({color, intensity, position}); -``` -#### Parameters - -* `color` - (*array*,) RGB color of point light source, default value is `[255, 255, 255]`. -* `intensity` - (*number*) Strength of point light source, default value is `1.0`. -* `position` - (*array*,) Location of point light source, default value is `[0, 0, 1]`. -* `attenuation` - (*array*,) Attenuation of point light source based on distance. -In order of Constant, Linear, Exponential components. -For details see [this tutorial](http://ogldev.atspace.co.uk/www/tutorial20/tutorial20.html). -Use `[1, 0, 0]` for no attenuation. Default value is `[0, 0, 1]`. diff --git a/docs/api-reference/core/material.md b/docs/api-reference/core/material.md deleted file mode 100644 index 8d128398a3..0000000000 --- a/docs/api-reference/core/material.md +++ /dev/null @@ -1,132 +0,0 @@ -# Material - -A material instance contains data that is used to populate uniforms for a specific shader stack - -See the developer-guide for more information about materials - - - -## Properties - -### doubleSided : Boolean - -The `doubleSided` property specifies whether the material is double sided. When this value is false, back-face culling is enabled. When this value is true, back-face culling is disabled and double sided lighting is enabled. The back-face must have its normals reversed before the lighting equation is evaluated. - - -### alphaMode : Enum - -The `alphaMode` property defines how the alpha value of the main factor and texture should be interpreted. - -`alphaMode` can be one of the following values: -* `OPAQUE` - The rendered output is fully opaque and any alpha value is ignored. -* `MASK` - The rendered output is either fully opaque or fully transparent depending on the alpha value and the specified alpha cutoff value. This mode is used to simulate geometry such as tree leaves or wire fences. -* `BLEND` - The rendered output is combined with the background using the normal painting operation (i.e. the Porter and Duff over operator). This mode is used to simulate geometry such as guaze cloth or animal fur. - -> The `alpha` value itself is typically defined in the `baseColor` prop, e.g. for the for metallic-roughness material model. - - -### alphaCutoff : Number - -When `alphaMode` is set to `MASK` the `alphaCutoff` property specifies the cutoff threshold. If the alpha value is greater than or equal to the `alphaCutoff` value then it is rendered as fully opaque, otherwise, it is rendered as fully transparent. `alphaCutoff` value is ignored for other modes. - - -### normalMap: Texture2D \| Sampler2D - -A tangent space normal map. Used to increase apparent detail of geometry. - - -### normalMapScale : Number - -Scale of normal map - - -### normalMapCoords : Number - -Set of texture coords to use for normal map - - -### occlusionMap: Texture2D \| Sampler2D - -A tangent space occlusion map. Used to indicate areas of indirect lighting, shading e.g. corners etc. - - -### occlusionMapScale : Number - -Scale of occlusion map - - -### occlusionMapCoords : Number - -Set of texture coords to use for occlusion map - - -### emissiveMap: Texture2D \| Sampler2D - -A tangent space emissive map. Used to add lights to models. For example, the headlights of a car model. - - -### emissiveMapScale : Number - -Scale of emissive map - - -### emissiveMapCoords : Number - -Set of texture coords to use for emissive map - - - - - -### Metallic-Roughness Material Model - -All parameters related to the metallic-roughness material model are defined under the `pbrMetallicRoughness` property of `material` object. The following example shows how a material like gold can be defined using the metallic-roughness parameters: - -```json -{ - "baseColor": [ 1.000, 0.766, 0.336, 1.0 ], - "metallic": 1.0, - "roughness": 0.0, - "baseColorMap": null, - "metallicRoughnessMap": null, -} -``` - -The metallic-roughness material model is defined by the following properties: - - -### `baseColor` : Number - -The base color of the material. The base color has two different interpretations depending on the value of metalness. When the material is a metal, the base color is the specific measured reflectance value at normal incidence (F0). For a non-metal the base color represents the reflected diffuse color of the material. In this model it is not possible to specify a F0 value for non-metals, and a linear value of 4% (0.04) is used. - - -### `metallic` : Number - -The metalness of the material - - -### `roughness` : Number - -The roughness of the material - - -### metallicRoughnessTexture - -The value for each property (`baseColor`, `metallic`, `roughness`) can be defined using factors or textures. The `metallic` and `roughness` properties are packed together in a single texture called `metallicRoughnessTexture`. - -```json -{ - "pbrMetallicRoughness": { - "baseColor": [ 0.5, 0.5, 0.5, 1.0 ], - "baseColorMap": null, - "baseColorMapCoords": 1, - "metallic": 1, - "roughness": 1, - "metallicRoughnessMap": null, - "metallicRoughnessMapScale": 1, - "metallicRoughnessMapCoords": 1, - }, -} -``` - -If a texture is not given, all respective texture components within this material model are assumed to have a value of `1.0`. If both factors and textures are present the factor value acts as a linear multiplier for the corresponding texture values. The `baseColorTexture` is in sRGB space and must be converted to linear space before it is used for any computations. diff --git a/docs/api-reference/core/materials/material.md b/docs/api-reference/core/materials/material.md deleted file mode 100644 index e2833fa0e1..0000000000 --- a/docs/api-reference/core/materials/material.md +++ /dev/null @@ -1,65 +0,0 @@ -# Material - -The `Material` class is the base class of materials. It is recommended that all materials implemente the following properties however you will need to check the documentation of each material: - - -## Common Materials Properties - -| Property | Default | Comments | -| --- | --- | --- | -| `doubleSided` | `false` | | -| `alphaMode` | `OPAQUE` | `OPAQUE`, `MASK` OR `BLEND` | - -### Common Materials Maps - -| Property | Default | Comments | -| --- | --- | --- | -| `normalTexture` | `null` | | -| `normalTextureScale` | `1` | | -| `normalTextureCoords` | `1` | | - - -## Property Descriptions - -### Double Sided - -The `doubleSided` property specifies whether the material is double sided. When this value is false, back-face culling is enabled. When this value is true, back-face culling is disabled and double sided lighting is enabled. The back-face must have its normals reversed before the lighting equation is evaluated. - - -### Alpha Coverage - -The `alpha` value is typically defined in the `baseColor` prop, e.g. for the for metallic-roughness material model. - -The `alphaMode` property defines how the alpha value of the main factor and texture should be interpreted. - -`alphaMode` can be one of the following values: -* `OPAQUE` - The rendered output is fully opaque and any alpha value is ignored. -* `MASK` - The rendered output is either fully opaque or fully transparent depending on the alpha value and the specified alpha cutoff value. This mode is used to simulate geometry such as tree leaves or wire fences. -* `BLEND` - The rendered output is combined with the background using the normal painting operation (i.e. the Porter and Duff over operator). This mode is used to simulate geometry such as guaze cloth or animal fur. - - When `alphaMode` is set to `MASK` the `alphaCutoff` property specifies the cutoff threshold. If the alpha value is greater than or equal to the `alphaCutoff` value then it is rendered as fully opaque, otherwise, it is rendered as fully transparent. `alphaCutoff` value is ignored for other modes. - ->**Implementation Note for Real-Time Rasterizers:** Real-time rasterizers typically use depth buffers and mesh sorting to support alpha modes. The following describe the expected behavior for these types of renderers. ->* `OPAQUE` - A depth value is written for every pixel and mesh sorting is not required for correct output. ->* `MASK` - A depth value is not written for a pixel that is discarded after the alpha test. A depth value is written for all other pixels. Mesh sorting is not required for correct output. ->* `BLEND` - Support for this mode varies. There is no perfect and fast solution that works for all cases. Implementations should try to achieve the correct blending output for as many situations as possible. Whether depth value is written or whether to sort is up to the implementation. For example, implementations can discard pixels which have zero or close to zero alpha value to avoid sorting issues. - - -## Common Material Maps - -The material definition provides for common maps that can also be used with different material models, including the metallic-roughness material model selected by the core glTF standard. - -| Map | Description | Rendering impact when map is not supported | -|---------- | ---------------------------- | ------------------------------------------- | -| Normal | A tangent space normal map. | Geometry will appear less detailed than authored. | -| Occlusion | Indicates areas of indirect lighting. | Model will appear brighter in areas that should be darker. | -| Emissive | Controls the color and intensity of the light being emitted by the material. | Model with lights will not be lit. For example, the headlights of a car model will be off instead of on. | - -Each material map has the following properties: - -* A texture (or sampler) -* A scale -* A texture coordinate set - - -> **Implementation Note:** If an implementation is resource-bound and cannot support all the maps defined it will drop these optional maps from the bottom. diff --git a/docs/api-reference/core/materials/pbr-material.md b/docs/api-reference/core/materials/pbr-material.md deleted file mode 100644 index 13262a9cd8..0000000000 --- a/docs/api-reference/core/materials/pbr-material.md +++ /dev/null @@ -1,77 +0,0 @@ -# PBRMaterial - -Implements the PBR (Physically-Based Rendering) material system specified in the core glTF standard. The metallic-roughness material model specified in the glTF2 standard enables glTF files to be rendered consistently across platforms. - -> glTF extensions that influence the material model are not currently supported. - -References: - -* This page draws a lot of content from [glTF 2.0 Materials section](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#materials). - - -## Extends Material - -`PBRMaterial` implements the common recommended material properties recommended in the base `Material` class. - - -### Metallic-Roughness Material Model - -All parameters related to the metallic-roughness material model are defined under the `pbrMetallicRoughness` property of `material` object. The following example shows how a material like gold can be defined using the metallic-roughness parameters: - -```json -{ - "baseColor": [ 1.000, 0.766, 0.336, 1.0 ], - "metallic": 1.0, - "roughness": 0.0, - "baseColorTexture": null, - "metallicRoughnessTexture": null, -} -``` - -The metallic-roughness material model is defined by the following properties: -* `baseColor` - The base color of the material -* `metallic` - The metalness of the material -* `roughness` - The roughness of the material - -The base color has two different interpretations depending on the value of metalness. When the material is a metal, the base color is the specific measured reflectance value at normal incidence (F0). For a non-metal the base color represents the reflected diffuse color of the material. In this model it is not possible to specify a F0 value for non-metals, and a linear value of 4% (0.04) is used. - -The value for each property (`baseColor`, `metallic`, `roughness`) can be defined using factors or textures. The `metallic` and `roughness` properties are packed together in a single texture called `metallicRoughnessTexture`. - -```json -{ - "pbrMetallicRoughness": { - "baseColor": [ 0.5, 0.5, 0.5, 1.0 ], - "baseColorTexture": null, - "baseColorTextureCoord": 1, - "metallic": 1, - "roughness": 1, - "metallicRoughnessTexture": null, - "metallicRoughnessTexture": null, - "metallicRoughnessTextureCoord": 1, - }, -} -``` - -If a texture is not given, all respective texture components within this material model are assumed to have a value of `1.0`. If both factors and textures are present the factor value acts as a linear multiplier for the corresponding texture values. The `baseColorTexture` is in sRGB space and must be converted to linear space before it is used for any computations. - -For example, assume a value of `[0.9, 0.5, 0.3, 1.0]` in linear space is obtained from an RGBA `baseColorTexture`, and assume that `baseColorFactor` is given as `[0.2, 1.0, 0.7, 1.0]`. -Then, the result would be -``` -[0.9 * 0.2, 0.5 * 1.0, 0.3 * 0.7, 1.0 * 1.0] = [0.18, 0.5, 0.21, 1.0] -``` - -### Calculating Reflectance - -The following equations show how to calculate bidirectional reflectance distribution function (BRDF) inputs (*cdiff*, *F0*, *α*) from the metallic-roughness material properties. In addition to the material properties, if a primitive specifies a vertex color using the attribute semantic property `COLOR_0`, then this value acts as an additional linear multiplier to `baseColor`. - -`const dielectricSpecular = rgb(0.04, 0.04, 0.04)` -
-`const black = rgb(0, 0, 0)` - -*cdiff* = `lerp(baseColor.rgb * (1 - dielectricSpecular.r), black, metallic)` -
-*F0* = `lerp(dieletricSpecular, baseColor.rgb, metallic)` -
-*α* = `roughness ^ 2` - - diff --git a/docs/api-reference/core/materials/phong-material.md b/docs/api-reference/core/materials/phong-material.md deleted file mode 100644 index 66a813ea54..0000000000 --- a/docs/api-reference/core/materials/phong-material.md +++ /dev/null @@ -1,31 +0,0 @@ -# PhongMaterial - -A material class specifies reflection properties of a shiny surface, uses [Blinn-Phong](https://en.wikipedia.org/wiki/Blinn%E2%80%93Phong_shading_model) model for underlying implementation. - - -## Usage - -Create a material class -```js -const phongMaterial = new PhongMaterial({ - ambient: 0.2, - diffuse: 0.5, - shininess: 32, - specularColor: [255, 255, 255] -}); -``` - -## Methods - -### constructor - -The constructor for the `PhongMaterial` class. Use this to create a new `PhongMaterial`. - -```js -const phongMaterial = new PhongMaterial({ambient, diffuse, shininess, specularColor}); -``` - -* `ambient` - (*number*,) Ambient light reflection ratio, default value is `0.4`. -* `diffuse` - (*number*) Diffuse light reflection ratio, default value is `0.6`. -* `shininess` - (*number*) Parameter to control specular highlight radius, default value is `32`. -* `specularColor` - (*array*) Color applied to specular lighting, default value is `[30, 30, 30]`. diff --git a/docs/api-reference/core/multipass/canvas.md b/docs/api-reference/core/multipass/canvas.md deleted file mode 100644 index 2ffb60b01a..0000000000 --- a/docs/api-reference/core/multipass/canvas.md +++ /dev/null @@ -1,106 +0,0 @@ -# Canvas (Experimental) - -> This document is still being written. - -`Canvas` is a unique class that makes it possible to use filter-style image processing shader modules in a standard JavaScript application, without using the rest of the luma.gl API. - -The `Canvas` class was inspired by the `canvas` class in the glfx API. - - -## Usage - - -```js - - - -``` - -## Methods - -### Canvas Constructor - -var canvas = new Canvas(); - -Before you can apply any filters you will need a canvas, which stores the result of the filters you apply. Canvas creation is done through `new Canvas()`, which creates and returns a new WebGL tag with additional methods specific to glfx.js. This call will throw an error message if the browser doesn't support WebGL. - -### Canvas.destroy() - -Textures will be garbage collected eventually when they are no longer referenced, but this method will free GPU resources immediately. - - -### installFiltersAsMethods(filters : Object) - -Installs a map of shader filters as methods on the `Canvas` instance, as an alternative to calling them using `Canvas.filter`. - -### replace(node : HTMLElement) - - -### setTexture(element) - -Creates a texture that initially stores the image from an HTML element. Notice that texture() is a method on a canvas object, which means if you want to use the same image on two canvas objects you will need two different textures, one for each canvas. - -* `element` - The HTML element to store in the texture, either an , a , or a