add a custom rendering example

_sidebar.md

@@ -15,7 +15,7 @@
   - [Making Elements](/guide/making-elements)
   - [Compatibility](/guide/compatibility)
   - [Debugging](/guide/debugging)
-  - [Custom Rendering](/guide/custom-rendering)
+  - [Custom Rendering](/guide/custom-rendering/)
   - [Contributing](/guide/contributing)
 
 - **Examples**

_sidebar.src.md

@@ -15,7 +15,7 @@
   - [Making Elements](/guide/making-elements)
   - [Compatibility](/guide/compatibility)
   - [Debugging](/guide/debugging)
-  - [Custom Rendering](/guide/custom-rendering)
+  - [Custom Rendering](/guide/custom-rendering/)
   - [Contributing](/guide/contributing)
 
 - **Examples**

guide/custom-rendering.md → guide/custom-rendering/README.md

@@ -60,5 +60,23 @@ someScene.drawScene = () => {
 }
 ```
 
-Note, the [`postprocessing`](https://npmjs.com/postprocessing) package provides
-an alternative set of post-processing effects.
+> [!Note]
+> The [`postprocessing`](https://npmjs.com/postprocessing) package provides an
+> alternative set of post-processing effects.
+
+# Example
+
+Here's an example that applies glitch effect using Three's built-in
+post-processing classes:
+
+<live-code src="./example.html"></live-code>
+
+> [!Note]
+> The `Motor.addRenderTask` part of the example calls `scene.needsUpdate()`
+> repeatedly because the `GlitchPass` applies an animated effect. If you are using
+> a pass that is not animated and needs to only render for a single frame, then
+> you do not need to make an update loop because the scene will update
+> automatically when any of its content changes. In that example, the scene has
+> no idea the `GlitchPass` exists because we've stepped outside of Lume's control
+> and are wiring in custom Three.js stuff, so the scene will not automatically
+> know that it should update.

guide/custom-rendering/example.html

@@ -0,0 +1,70 @@
+<script src="../../importmap.js"></script>
+
+<lume-scene webgl id="scene">
+	<lume-camera-rig horizontal-angle="-30" vertical-angle="30"></lume-camera-rig>
+	<lume-box size="100 100 100" mount-point="0.5 0.5 0.5"></lume-box>
+	<lume-point-light position="200 400 500" color="deeppink" intensity="0.6"></lume-point-light>
+	<lume-point-light position="-200 -400 -500" color="royalblue" intensity="0.6"></lume-point-light>
+</lume-scene>
+
+<style>
+	html,
+	body {
+		margin: 0;
+		height: 100%;
+	}
+	lume-element3d {
+		padding: 5px;
+	}
+</style>
+
+<script type="module">
+	import {Motor} from 'lume'
+	import {EffectComposer} from 'three/examples/jsm/postprocessing/EffectComposer.js'
+	import {RenderPass} from 'three/examples/jsm/postprocessing/RenderPass.js'
+	import {GlitchPass} from 'three/examples/jsm/postprocessing/GlitchPass.js'
+	import {OutputPass} from 'three/examples/jsm/postprocessing/OutputPass.js'
+
+	const composer = new EffectComposer(scene.glRenderer)
+
+	function setDimensions() {
+		composer.setPixelRatio(window.devicePixelRatio)
+		const resize = () => composer.setSize(scene.clientWidth, scene.clientHeight)
+		const observer = new ResizeObserver(resize)
+		observer.observe(scene)
+	}
+
+	// If you do things manually with Three.js, you need to make sure to set the
+	// proper rendering dimensions. Comment this out and it will still work, but
+	// the demo may be lower resolution and look pixelated.
+	setDimensions()
+
+	const renderPass = new RenderPass(scene.three, scene.threeCamera)
+	composer.addPass(renderPass)
+
+	const glitchPass = new GlitchPass()
+	composer.addPass(glitchPass)
+
+	const outputPass = new OutputPass()
+	composer.addPass(outputPass)
+
+	scene.drawScene = () => {
+		// If there are multiple cameras in the Lume scene, make sure to always
+		// use the currently-active camera.
+		renderPass.camera = scene.threeCamera
+
+		composer.render()
+	}
+
+	// If you need the scene to be continuously rendering for a certain
+	// post-processing effects (for example, the GlitchPass is animated over
+	// time), then make a loop that calls scene.needsUpdate() repeatedly. Here
+	// we do that with Lume's Motor:
+	Motor.addRenderTask(() => scene.needsUpdate())
+
+	// Alternatively, make an rAF loop:
+	// requestAnimationFrame(function loop() {
+	// 	scene.needsUpdate()
+	// 	requestAnimationFrame(loop)
+	// })
+</script>