From ca3cf0474f2dd17450eba153be60e77fb3e1560b Mon Sep 17 00:00:00 2001 From: Joe Pea Date: Fri, 5 Jan 2024 13:53:20 -0800 Subject: [PATCH] =?UTF-8?q?Remove=20"under=20construction"=20notes=20and?= =?UTF-8?q?=20add=20fill=20in=20initial=20content!=20=F0=9F=8E=89=20In=20t?= =?UTF-8?q?he=20process,=20add=20more=20demos=20for=20explanation,=20as=20?= =?UTF-8?q?well=20as=20a=20new=20Texture=20Shadow=20demo=20that=20shows=20?= =?UTF-8?q?how=20to=20cast=20a=20shadow=20based=20on=20the=20non-transpare?= =?UTF-8?q?nt=20parts=20of=20a=20textured=20mesh.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- _sidebar.md | 11 +- _sidebar.src.md | 11 +- .../geometries/MixedPlaneGeometryBehavior.md | 2 +- .../materials/MixedPlaneMaterialBehavior.md | 2 +- api/core/Scene.md | 10 +- api/core/Transformable.md | 2 +- api/meshes/MixedPlane.md | 2 +- api/models/ColladaModel.md | 21 +- api/models/FbxModel.md | 15 +- api/models/GltfModel.md | 15 +- api/models/ObjModel.md | 11 +- api/models/TdsModel.md | 15 +- examples/autolayout-declarative.md | 4 +- examples/autolayout-imperative.md | 4 +- .../README.md} | 2 +- .../example.html} | 11 +- examples/buttons-with-shadow/no-css.html | 12 + examples/buttons-with-shadow/no-webgl.html | 12 + examples/disco-helmet/README.md | 2 +- .../{disco-helmet.html => example.html} | 0 examples/ripple-flip.md | 2 +- examples/skateboard-configurator/README.md | 25 +- examples/texture-shadow/README.md | 6 + examples/texture-shadow/example.html | 46 +++ guide/debugging.md | 2 +- guide/external-assets/README.md | 31 +- guide/making-elements.md | 11 +- guide/positioning/README.md | 371 +++++++++++++++++- guide/reactivity.md | 4 +- guide/rendering-modes.md | 111 +++++- .../{scene-graph.md => scene-graph/README.md} | 88 ++--- guide/scene-graph/example.html | 57 +++ guide/sizing.md | 155 +++++++- index.html | 3 +- 35 files changed, 937 insertions(+), 141 deletions(-) rename examples/{buttons-with-shadow.md => buttons-with-shadow/README.md} (89%) rename examples/{buttons-with-shadow.html => buttons-with-shadow/example.html} (95%) create mode 100644 examples/buttons-with-shadow/no-css.html create mode 100644 examples/buttons-with-shadow/no-webgl.html rename examples/disco-helmet/{disco-helmet.html => example.html} (100%) create mode 100644 examples/texture-shadow/README.md create mode 100644 examples/texture-shadow/example.html rename guide/{scene-graph.md => scene-graph/README.md} (55%) create mode 100644 guide/scene-graph/example.html diff --git a/README.md b/README.md index 412e1a4..66fb258 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ cement wall -- but notice: and this gives us a version of the same concept with more realism: - + Lume is built as [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) (also diff --git a/_sidebar.md b/_sidebar.md index 84791b6..564e9f8 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -4,14 +4,14 @@ - [Install](/guide/install/) - [Making a Scene](/guide/making-a-scene) - [Custom Element Names](/guide/custom-element-names) - - [Scene Graph](/guide/scene-graph) + - [Scene Graph](/guide/scene-graph/) - [Common Attributes](/guide/common-attributes) - - [Positioning](/guide/positioning/) - [Sizing](/guide/sizing) + - [Positioning](/guide/positioning/) - [Rendering Modes](/guide/rendering-modes) - - [Reactivity](/guide/reactivity) - [Cameras](/guide/cameras/) - [External Assets](/guide/external-assets/) + - [Reactivity](/guide/reactivity) - [Making Elements](/guide/making-elements) - [Compatibility](/guide/compatibility) - [Debugging](/guide/debugging) @@ -29,7 +29,8 @@ - [✨ Velodyne Lidar Scan](/examples/velodyne-lidar-scan/ ':class=no-sublist') - [🏎️ Shelby GT350 Points](/examples/shelby-gt350-points/ ':class=no-sublist') - [Disco Helmet](/examples/disco-helmet/ ':class=no-sublist') - - [Buttons with shadow](/examples/buttons-with-shadow.md ':class=no-sublist') + - [Buttons with shadow](/examples/buttons-with-shadow/ ':class=no-sublist') + - [Texture Shadow](/examples/texture-shadow/ ':class=no-sublist') - [Rounded rectangle](/examples/rounded-rectangle.md ':class=no-sublist') - [Ripple flip](/examples/ripple-flip.md ':class=no-sublist') - [Morphing spiral](/examples/spiral.md ':class=no-sublist') @@ -43,6 +44,8 @@ - **Packages** - [element-behaviors](/guide/includes/lume-element-behaviors) + - [classy-solid](/guide/includes/classy-solid) + - [@lume/element](/guide/includes/lume-element) - [@lume/autolayout](/guide/layouts-with-autolayout) - [@lume/three-meshline](/three-meshline/) diff --git a/_sidebar.src.md b/_sidebar.src.md index d6c70a3..dd24587 100644 --- a/_sidebar.src.md +++ b/_sidebar.src.md @@ -4,14 +4,14 @@ - [Install](/guide/install/) - [Making a Scene](/guide/making-a-scene) - [Custom Element Names](/guide/custom-element-names) - - [Scene Graph](/guide/scene-graph) + - [Scene Graph](/guide/scene-graph/) - [Common Attributes](/guide/common-attributes) - - [Positioning](/guide/positioning/) - [Sizing](/guide/sizing) + - [Positioning](/guide/positioning/) - [Rendering Modes](/guide/rendering-modes) - - [Reactivity](/guide/reactivity) - [Cameras](/guide/cameras/) - [External Assets](/guide/external-assets/) + - [Reactivity](/guide/reactivity) - [Making Elements](/guide/making-elements) - [Compatibility](/guide/compatibility) - [Debugging](/guide/debugging) @@ -29,7 +29,8 @@ - [✨ Velodyne Lidar Scan](/examples/velodyne-lidar-scan/ ':class=no-sublist') - [🏎️ Shelby GT350 Points](/examples/shelby-gt350-points/ ':class=no-sublist') - [Disco Helmet](/examples/disco-helmet/ ':class=no-sublist') - - [Buttons with shadow](/examples/buttons-with-shadow.md ':class=no-sublist') + - [Buttons with shadow](/examples/buttons-with-shadow/ ':class=no-sublist') + - [Texture Shadow](/examples/texture-shadow/ ':class=no-sublist') - [Rounded rectangle](/examples/rounded-rectangle.md ':class=no-sublist') - [Ripple flip](/examples/ripple-flip.md ':class=no-sublist') - [Morphing spiral](/examples/spiral.md ':class=no-sublist') @@ -43,6 +44,8 @@ - **Packages** - [element-behaviors](/guide/includes/lume-element-behaviors) + - [classy-solid](/guide/includes/classy-solid) + - [@lume/element](/guide/includes/lume-element) - [@lume/autolayout](/guide/layouts-with-autolayout) - [@lume/three-meshline](/three-meshline/) diff --git a/api/behaviors/mesh-behaviors/geometries/MixedPlaneGeometryBehavior.md b/api/behaviors/mesh-behaviors/geometries/MixedPlaneGeometryBehavior.md index 4406102..cc158bd 100644 --- a/api/behaviors/mesh-behaviors/geometries/MixedPlaneGeometryBehavior.md +++ b/api/behaviors/mesh-behaviors/geometries/MixedPlaneGeometryBehavior.md @@ -5,7 +5,7 @@ Used as the geometry for [``](../../../meshes/MixedPlane) elements. The planes are thin boxes instead of actually planes, otherwise Three.js cannot currently cast shadows from plane geometries. - + diff --git a/api/behaviors/mesh-behaviors/materials/MixedPlaneMaterialBehavior.md b/api/behaviors/mesh-behaviors/materials/MixedPlaneMaterialBehavior.md index 3279dfe..b90fcfe 100644 --- a/api/behaviors/mesh-behaviors/materials/MixedPlaneMaterialBehavior.md +++ b/api/behaviors/mesh-behaviors/materials/MixedPlaneMaterialBehavior.md @@ -3,7 +3,7 @@ Used as the material for [``](../../../meshes/MixedPlane) elements. - + ## Properties diff --git a/api/core/Scene.md b/api/core/Scene.md index 5653edb..93c05b7 100644 --- a/api/core/Scene.md +++ b/api/core/Scene.md @@ -73,7 +73,7 @@ top of the WebGL layer instead of below. -### .shadowmapType :id=shadowmapType +### .shadowMode :id=shadowMode *attribute* @@ -89,6 +89,14 @@ Applies only if [`webgl`](#webgl) is `true`. +### .shadowmapType :id=shadowmapType + +Deprecated, use [`shadowMode`](#shadowmaptype) instead. + +*attribute* + + + ### .vr :id=vr *attribute* diff --git a/api/core/Transformable.md b/api/core/Transformable.md index 8de36e9..f51713a 100644 --- a/api/core/Transformable.md +++ b/api/core/Transformable.md @@ -78,7 +78,7 @@ at each origin point on each cube. All cubes are initially oriented the same, but as you move the sliders, each cube rotates around their specific origin. - + diff --git a/api/meshes/MixedPlane.md b/api/meshes/MixedPlane.md index a2c656d..33febb1 100644 --- a/api/meshes/MixedPlane.md +++ b/api/meshes/MixedPlane.md @@ -16,7 +16,7 @@ content will not receal 3D content that would be expected to be behind them. See [`MixedPlaneGeometryBehavior`](../behaviors/mesh-behaviors/geometries/MixedPlaneGeometryBehavior) and [`MixedPlaneMaterialBehavior`](../behaviors/mesh-behaviors/materials/MixedPlaneMaterialBehavior) for available properties. - + ## Properties diff --git a/api/models/ColladaModel.md b/api/models/ColladaModel.md index fa2cc0b..e097907 100644 --- a/api/models/ColladaModel.md +++ b/api/models/ColladaModel.md @@ -1,38 +1,45 @@ -# class ColladaModel :id=ColladaModel +# class ColladaModel extends [Element3D](../core/Element3D.md) :id=ColladaModel -> :construction: :hammer: Under construction! :hammer: :construction: +Defines the `` element, short for ``, for loading 3D models in the Collada format (`.dae` +files). -Defines the `` element, for loading 3D -models in the Collada format (.dae files). It is similar to an `` tag, but for 3D. +See [`ColladaModelBehavior`](../behaviors/mesh-behaviors/models/ColladaModelBehavior) +for attributes/properties available on this element. HTML Example: ```html - + + ``` JavaScript Example: ```js const scene = new Scene +scene.webgl = true document.body.append(scene) const model = new ColladaModel model.src = 'path/to/model.dae' +model.on('MODEL_LOAD', () => console.log('loaded')) scene.add(model) ``` +Inherits properties from [Element3D](../core/Element3D.md). - - +Inherits methods from [Element3D](../core/Element3D.md). \ No newline at end of file diff --git a/api/models/FbxModel.md b/api/models/FbxModel.md index 11d7f17..448fa9d 100644 --- a/api/models/FbxModel.md +++ b/api/models/FbxModel.md @@ -1,26 +1,33 @@ # class FbxModel :id=FbxModel -> :construction: :hammer: Under construction! :hammer: :construction: +Defines the `` element, short for ``, for loading 3D models in the FBX format (`.fbx` +files). -Defines the `` element, for loading 3D -models in the FBX format (.fbx files). It is similar to an `` tag, but for 3D. +See [`FbxModelBehavior`](../behaviors/mesh-behaviors/models/FbxModelBehavior) +for attributes/properties available on this element. HTML Example: ```html - + + ``` JavaScript Example: ```js const scene = new Scene +scene.webgl = true document.body.append(scene) const model = new FbxModel model.src = 'path/to/model.fbx' +model.on('MODEL_LOAD', () => console.log('loaded')) scene.add(model) ``` diff --git a/api/models/GltfModel.md b/api/models/GltfModel.md index 43cfe14..83d77c8 100644 --- a/api/models/GltfModel.md +++ b/api/models/GltfModel.md @@ -1,26 +1,33 @@ # class GltfModel :id=GltfModel -> :construction: :hammer: Under construction! :hammer: :construction: +Defines the `` element, short for ``, for loading 3D models in the glTF format (`.gltf` or +`.glb` files). -Defines the `` element, for loading 3D -models in the glTF format. It is similar to an `` tag, but for 3D. +See [`GltfModelBehavior`](../behaviors/mesh-behaviors/models/GltfModelBehavior) +for attributes/properties available on this element. HTML Example: ```html - + + ``` JavaScript Example: ```js const scene = new Scene +scene.webgl = true document.body.append(scene) const model = new GltfModel model.src = 'path/to/model.gltf' +model.on('MODEL_LOAD', () => console.log('loaded')) scene.add(model) ``` diff --git a/api/models/ObjModel.md b/api/models/ObjModel.md index 6670eb5..fcfc614 100644 --- a/api/models/ObjModel.md +++ b/api/models/ObjModel.md @@ -1,24 +1,31 @@ # class ObjModel :id=ObjModel -Defines the `` element, which is short for ``. +Defines the `` element, short for ``, for loading 3D models in the OBJ format (`.obj` files +paired with `.mtl` files). HTML Example: ```html - + + ``` JavaScript Example: ```js const scene = new Scene +scene.webgl = true document.body.append(scene) const model = new ObjModel model.obj = 'path/to/model.obj' model.mtl = 'path/to/model.mtl' +model.on('MODEL_LOAD', () => console.log('loaded')) scene.add(model) ``` diff --git a/api/models/TdsModel.md b/api/models/TdsModel.md index e98a13c..6448d46 100644 --- a/api/models/TdsModel.md +++ b/api/models/TdsModel.md @@ -1,26 +1,33 @@ # class TdsModel :id=TdsModel -> :construction: :hammer: Under construction! :hammer: :construction: +Defines the `` element, short for ``, for loading 3D models in the 3DS format (`.3ds` +files). -Defines the `` element, for loading 3D -models in the 3DS format (.3ds files). It is similar to an `` tag, but for 3D. +See [`TdsModelBehavior`](../behaviors/mesh-behaviors/models/TdsModelBehavior) +for attributes/properties available on this element. HTML Example: ```html - + + ``` JavaScript Example: ```js const scene = new Scene +scene.webgl = true document.body.append(scene) const model = new TdsModel model.src = 'path/to/model.3ds' +model.on('MODEL_LOAD', () => console.log('loaded')) scene.add(model) ``` diff --git a/examples/autolayout-declarative.md b/examples/autolayout-declarative.md index a924c7d..395aed9 100644 --- a/examples/autolayout-declarative.md +++ b/examples/autolayout-declarative.md @@ -37,7 +37,7 @@ > - This is a paragraph of text to show that it reflows when the size of the layout changes size so that the awesomeness can be observed in its fullness. This is a paragraph of text to show that it reflows when the size of the layout changes size so that the awesomeness can be observed in its fullness. This is a paragraph of text to show that it reflows when the size of the layout changes size so that the awesomeness can be observed in its fullness. - + + ` + document.write(html) + diff --git a/examples/buttons-with-shadow/no-webgl.html b/examples/buttons-with-shadow/no-webgl.html new file mode 100644 index 0000000..e7d3bcd --- /dev/null +++ b/examples/buttons-with-shadow/no-webgl.html @@ -0,0 +1,12 @@ + + diff --git a/examples/disco-helmet/README.md b/examples/disco-helmet/README.md index 74b549c..ed19b56 100644 --- a/examples/disco-helmet/README.md +++ b/examples/disco-helmet/README.md @@ -1,3 +1,3 @@ # Disco Helmet - + diff --git a/examples/disco-helmet/disco-helmet.html b/examples/disco-helmet/example.html similarity index 100% rename from examples/disco-helmet/disco-helmet.html rename to examples/disco-helmet/example.html diff --git a/examples/ripple-flip.md b/examples/ripple-flip.md index 5848965..e4b46f8 100644 --- a/examples/ripple-flip.md +++ b/examples/ripple-flip.md @@ -1,6 +1,6 @@ # Ripple flip - + -[classy-solid](./includes/classy-solid.md ':include') +For more on reactivity and templating, see the +[`classy-solid`](./includes/classy-solid.md) and +[`@lume/element`](./includes/lume-element) packages. diff --git a/guide/rendering-modes.md b/guide/rendering-modes.md index 4ead1a4..298beb1 100644 --- a/guide/rendering-modes.md +++ b/guide/rendering-modes.md @@ -1,3 +1,112 @@ # Rendering Modes -> :construction: :hammer: Under construction! :hammer: :construction: +A `` element has several render modes: + +## WebGL + +This mode is not enabled by default, enable it with a scene's `webgl` attribute: + +```html + +``` + +This mode rendering mode is powered by the GPU using WebGL (soon WebGPU) with +the help of Three.js. This mode supports features such as: + +- fully-3D shapes such as boxes, spheres, or 3D models loaded from external + files +- dynamic shadows and lighting +- other GPU shaders effects like glows, refractions through transparent objects, + reflections, etc. +- fluid morphing of shapes + +Here's an example rendered with WebGL only. The demo loads a 3D model from a +`.gltf` file (glTF is a [3D file format](https://khronos.org/gltf)), illuminates +the model using light sources, visualizes the positions of the light sources +using small spheres, and renders a "floor" using a plane: + + + +> :bulb:**Tip:** +> +> The disco helmet example does not use CSS rendering for any visible effects, +> but CSS rendering is enabled (by default) because it makes debugging WebGL +> scenes easier. For example, see the [Debugging](./debugging.md) guide to learn +> about debugging 3D scenes in your browser's element inspector. + +## CSS + +This mode is enabled by default, disable it with a scene's `enable-css` attribute: + +```html + +``` + +This rendering mode uses CSS 3D transforms to move flat surfaces in 3D space. + +- CSS 3D rendering is limited to flat rectangles with borders, background + colors, and images. +- CSS 3D cannot do shading, for example no dynamic shadows or lighting, no + special effects like refractions or reflections, etc. +- No morphing of shapes, CSS 3D objects are always flat rectangles (with + optional border radius). + +The next example uses only CSS rendering to move flat surfaces in 3D space. Try +dragging the view to change the camera angle to more easily see how the flat +surfaces are positioned. + + + +## Mixed + +Mixed mode is when both WebGL and CSS rendering modes are enabled, and in +particular when both modes are used to show visual effects at the same time. +Mixed mode is not a mode on its own, but rather when both of the other modes are +combined. + +Enabling this mode requires enabling WebGL mode only, as CSS is mode is already +enabled by default: + +```html + +``` + +Lume's ability to mix WebGL and CSS modes together, out of the box, allows us to +achieve scenarios where CSS content appears to be seamlessly rendered alongside +WebGL content, with CSS content event appearing to intersect with WebGL content. +Object rendered in either mode will be aligned together in the same 3D space. + +The following example shows traditional `