Scene background article

website/.vitepress/config.ts

@@ -46,6 +46,7 @@ export default defineConfig({
         items: [
           {text: 'Mesh Lines (Spiral)', link: 'notes/fat-lines'},
           {text: 'glTF Mesh Lines', link: 'notes/gltf-mesh-lines'},
+          {text: 'Setting Background', link: 'notes/scene-background'},
         ]
       },
       {

website/notes/gltf-mesh-lines.md

@@ -3,7 +3,10 @@ prev:
   text: 'Fat Lines'
   link: './fat-lines'
 
-next: false
+next: 
+  text: 'Setting Background Color and Images'
+  link: './scene-background'
+
 aside: false
 ---
 

website/notes/scene-background.md

@@ -0,0 +1,145 @@
+---
+prev:
+  text: 'GLTF Fat/Mesh Lines'
+  link: './gltf-mesh-lines'
+
+next: false
+aside: false
+---
+
+# Setting Background Color and Images
+
+The Background in `threepipe` is managed by the `scene` in the `viewer`.
+
+It can be set to a color(using [`scene.setBackgroundColor`](https://threepipe.org/docs/classes/RootScene.html#setBackgroundColor)), a flat 2d or environment map texture(using [`scene.background`](https://threepipe.org/docs/classes/RootScene.html#background)), or both. 
+When both are set, the color is multiplied with the texture, so it can be used to tint the background.
+
+The final intensity(brightness) of the background can also be controlled with the [`scene.backgroundIntensity`](https://threepipe.org/docs/classes/RootScene.html#backgroundintensity) property on the scene.
+
+## Background Color
+
+To set the background color, use the `setBackgroundColor` method on the scene. This will set a solid color as the background.
+
+```javascript
+viewer.scene.setBackgroundColor(0x000000); // Set background to black
+```
+
+::: info
+The color passed in can be a number (`0xff00ff`), a string(`'#ff00ff'`, `'rgba(255, 0, 255, 1)'`), or a `Color` object.
+
+It will be converted to a `Color` object internally and set to the `backgroundColor` property of the scene.
+:::
+
+To remove the background color, set it to `null`:
+
+```javascript
+viewer.scene.setBackgroundColor(null); // Remove background color
+```
+
+To get the current background color, access the [`backgroundColor`](https://threepipe.org/docs/classes/RootScene.html#backgroundcolor) property of the scene:
+
+```javascript
+const currentColor = viewer.scene.backgroundColor; // Get current background color
+console.log('#' + currentColor.getHexString()); // Log color in hex format
+```
+
+## Background Texture
+
+An Image/Texture can be set as the background using the `viewer.setBackgroundMap` function by passing in a url, `IAsset`, `File` object or a loaded `Texture`.
+
+```javascript
+viewer.setBackgroundMap('https://example.com/path/to/texture.jpg'); // Set background texture
+// or load an env map as background
+viewer.setBackgroundMap('https://example.com/path/to/envmap.hdr', { 
+    setEnvironment: true // if set to true, the environment map will also be set as the scene's background
+});
+// or set the background property directly
+viewer.scene.background = viewer.load<ITexture>('https://example.com/path/to/texture.jpg')
+```
+
+If a color is set, it will be multiplied with the texture, allowing you to tint the background.
+
+To remove the background texture, simply set it to `null`:
+
+```javascript
+viewer.setBackgroundMap(null)
+// or 
+viewer.scene.background = null;
+```
+
+::: tip
+When setting a flat texture as the background, it will be stretched to fill the entire viewport.
+
+This can be changed by either setting the `mapping` property of the texture to `EquirectangularReflectionMapping`. (it is set automatically when loading an appropriate HDR/EXR texture)
+:::
+
+## Transparent Background
+
+To set a transparent background, you can set both the `scene.background` and `scene.backgroundColor` to `null`.
+
+```javascript
+viewer.scene.background = null; // Remove background texture
+viewer.scene.setBackgroundColor(null); // Remove background color
+```
+
+::: info RGBM Rendering Mode
+`ThreeViewer` uses `rgbm` rendering by default, which doesn't directly support transparent backgrounds.
+
+To use transparent background with `rgbm` mode, `clipBackground` function in `ViewerRenderManager.screenPass` is used. 
+This clips/removes the background color from the final render, allowing for a transparent background effect.
+:::
+
+## Clip Background
+
+In many cases, you may want to render the background color so that it can be used by plugins/post-processing effects like bloom, reflections, etc but composite the render with transparency over other content.
+
+This can be achieved by setting the `clipBackground` property of `ScreenPass` in the `ViewerRenderManager`. This renders the background color and texture normally, but clips it from the final render, allowing for a transparent background effect.
+
+```javascript
+viewer.renderManager.screenPass.clipBackground = true; // Enable clipping of background
+```
+
+Note that this is also automatically set when using `rgbm` rendering mode, and `null` for the background. But it will render the background first as black and clip it.
+So, when using `rgbm`, set the background color to an ideal color for the scene and use `clipBackground` to remove it.
+
+## Background Intensity
+
+The intensity of the background can be controlled using the `backgroundIntensity` property of the scene. This property is a multiplier for the background color and texture.
+
+This allows you to adjust the brightness of the background without changing the color or texture itself and even achieve greater than 100% brightness backgrounds for HDR rendering
+
+```javascript
+viewer.scene.backgroundIntensity = 0.5; // Set background intensity to 50%
+viewer.scene.backgroundIntensity = 5; // Set background intensity to 500%
+```
+
+## Pan/Scale Background
+
+To adjust the position or scale of the background texture, you can modify the `offset`, `center`, `repeat`, `rotation` properties of the texture. This allows you to pan or scale the background texture as needed.
+
+```javascript
+const backgroundTexture = viewer.scene.background;
+if (backgroundTexture) {
+    backgroundTexture.offset.set(0.1, 0.1); // Move texture by 10% in both x and y directions
+    backgroundTexture.repeat.set(2, 2); // Repeat texture twice in both x and y directions
+    backgroundTexture.rotation = Math.PI / 4; // Rotate texture by 45 degrees
+}
+```
+
+For equirect textures, `rotation` can be set to rotate the texture around the y-axis, which can be useful for adjusting the orientation of the environment map.
+
+```javascript
+if (backgroundTexture && backgroundTexture.mapping === EquirectangularReflectionMapping) {
+    backgroundTexture.rotation = Math.PI / 2; // Rotate environment map by 90 degrees
+}
+```
+
+[//]: # (TODO - add example how to adjust background like css background-position, background-size, etc)
+
+## Serialization
+
+The background color and texture can be serialized to JSON along with the scene.
+
+Since the scene object is part of the viewer configuration when saving a glb with config, it is also saved and applied when loading the glb.
+
+The serialization supports colors, image urls, embedded textures with formats that require external loaders like HDR, EXR, etc.