-
-
-
-
-```
-
-```js demo.js [active]
-/**
- * @name [textmode.js] Video Example
- * @description Real-time video-to-ASCII conversion using textmode.js
- * @author humanbydefinition
- * @link https://github.com/humanbydefinition/textmode.js
- */
-
-class VideoTextmodeDemo {
- constructor() {
- this.textmodifier = null;
- this.video = null;
- this.isTextmodeVisible = true;
-
- this.init();
- }
-
- async init() {
- this.setupVideoElement();
- await this.setupTextmode();
- this.setupControls();
- }
-
- setupVideoElement() {
- this.video = document.getElementById('myVideo');
- }
-
- async setupTextmode() {
- // Initialize textmode.js with the video element
- this.textmodifier = textmode.create({
- fontSize: 8,
- canvas: this.video,
- overlay: true
- });
-
- this.textmodifier.setup(() => {
- // Configure overlay settings
- this.textmodifier.overlay
- .characters(" .:-=+*#%@") // Character set for brightness mapping
- .cellColorMode("fixed") // Use fixed cell color
- .cellColor(0, 0, 0) // Black cell background
- .charColorMode("sampled") // Sample character color from image
- .background(0, 0, 0, 255); // Black background for transparent pixels
- });
-
- this.textmodifier.draw(() => {
- this.textmodifier.background(0);
- this.textmodifier.image(this.textmodifier.overlay, this.textmodifier.grid.cols, this.textmodifier.grid.rows);
- });
- }
-
- setupControls() {
- document.getElementById('playBtn').addEventListener('click', () => {
- this.video?.play();
- });
-
- document.getElementById('pauseBtn').addEventListener('click', () => {
- this.video?.pause();
- });
- }
-}
-
-// Initialize when DOM is ready
-document.addEventListener('DOMContentLoaded', () => {
- new VideoTextmodeDemo();
-});
-```
-
-:::
\ No newline at end of file
diff --git a/docs/examples/integration/webcam.md b/docs/examples/integration/webcam.md
index 6df3e622..5aa2c2ca 100644
--- a/docs/examples/integration/webcam.md
+++ b/docs/examples/integration/webcam.md
@@ -69,6 +69,7 @@ description: Render a live webcam feed as real-time textmode ASCII art using tex
+
@@ -131,14 +132,15 @@ async function initWebcam() {
// Initialize textmode.js overlay on webcam
tm = textmode.create({
- canvas: video,
- overlay: true,
+ plugins: [OverlayPlugin],
fontSize: 8
});
+ const source = tm.overlay.setTarget(video);
+
tm.setup(() => {
// Configure overlay settings for webcam
- tm.overlay
+ source
.characters(" .:-=+*#%@") // Character set for brightness mapping
.cellColorMode("fixed") // Use fixed cell color
.cellColor(0, 0, 0, 0) // Transparent cell background
@@ -151,7 +153,7 @@ async function initWebcam() {
tm.background(0, 0, 0, 255);
// Draw the converted webcam feed
- tm.image(tm.overlay, tm.grid.cols, tm.grid.rows);
+ tm.image(source, tm.grid.cols, tm.grid.rows);
});
} catch (err) {
@@ -174,18 +176,13 @@ async function initWebcam() {
}
}
-// Handle window resize
-function handleResize() {
- // Overlay mode follows the video element automatically.
- // No explicit textmode.js resize call is needed here.
-}
-
// Initialize when page loads
window.addEventListener('load', initWebcam);
-window.addEventListener('resize', handleResize);
// Cleanup on page unload
window.addEventListener('beforeunload', () => {
+ tm?.destroy();
+
if (video && video.srcObject) {
const tracks = video.srcObject.getTracks();
tracks.forEach(track => track.stop());
diff --git a/docs/framework-integration.md b/docs/framework-integration.md
index 3f401f7b..b5f71821 100644
--- a/docs/framework-integration.md
+++ b/docs/framework-integration.md
@@ -122,9 +122,11 @@ It simply samples a live `canvas` or `video` element as media input. That means:
- you can show both at once, hide one, or position them independently
- sizing and layout are entirely up to your application
+The same WebGL drawing-buffer rule applies here: an independently rendered WebGL canvas must use `preserveDrawingBuffer: true`, or the application must sample it synchronously before the browser is allowed to discard its contents.
+
## 4. Share an existing WebGL context
-If another library already owns a `WebGL2RenderingContext`, pass it through [`gl`](/api/textmode.js/type-aliases/TextmodeOptions#gl):
+If another library already owns a `WebGL2RenderingContext` and both renderers intentionally share one canvas, pass it through [`gl`](/api/textmode.js/type-aliases/TextmodeOptions#gl):
```js
const t = textmode.create({
@@ -132,36 +134,36 @@ const t = textmode.create({
});
```
-This tells `textmode.js` to render through the host library's existing context instead of creating its own.
-
-That path is especially useful for WebGL-based frameworks such as `three.js`, `Babylon.js`, or `A-Frame`.
+This is an advanced single-context integration, not a DOM overlay. Both renderers mutate the same WebGL state and present to the same canvas, so the application must establish render order and restore any renderer-specific state between them.
-It is commonly paired with [`createTexture()`](/api/textmode.js/classes/Textmodifier#createtexture) so the host renderer can draw first and `textmode.js` can reinterpret the same canvas as a live source:
+For example, a deliberately coordinated Three.js integration can render the host scene first and then let `textmode.js` replace the shared canvas output:
```js
const t = textmode.create({
gl: renderer.getContext(),
});
-let sceneTex;
-
t.setup(() => {
- sceneTex = t.createTexture(renderer.domElement);
+ // Configure the textmode scene.
});
-t.draw(() => {
- t.clear();
- t.image(sceneTex, t.grid.cols, t.grid.rows);
+t.noLoop();
+
+renderer.setAnimationLoop(() => {
+ renderer.render(scene, camera);
+ renderer.resetState();
+ t.redraw();
+ renderer.resetState();
});
```
-When you pass `gl`, the host framework still owns the underlying canvas and context. Calling [`destroy()`](/api/textmode.js/classes/Textmodifier#destroy) cleans up `textmode.js` resources, but it does not tear down the external canvas or external context.
+Do not combine an independently running `createTexture(renderer.domElement)` loop with shared `gl` as a default pattern: the source and destination would be the same canvas, and either renderer may overwrite state before the other finishes. When you pass `gl`, the host framework still owns the underlying canvas and context. Calling [`destroy()`](/api/textmode.js/classes/Textmodifier#destroy) cleans up `textmode.js` resources, but it does not tear down the external canvas or external context.
## Render-loop coordination
-Many frameworks already have their own animation loop. `textmode.js` does too.
+Many frameworks already have their own animation loop. `textmode.js` does too. For normal overlay integrations, let both loops run independently; the examples below all use that pattern.
-You can let both loops run independently, but when you want deterministic ordering it is better to let the host render first and then trigger `textmode.js` manually:
+When deterministic ordering is a requirement, such as a shared context or an unpreserved source captured immediately after rendering, coordinate the loops explicitly:
```js
t.noLoop();
@@ -174,7 +176,7 @@ function animate() {
}
```
-This is especially useful with shared textures or shared WebGL contexts, where you want `textmode.js` to sample the latest host frame immediately after it is rendered.
+This advanced pattern is especially useful with shared textures or shared WebGL contexts. It is not required for ordinary overlay sketches whose host drawing buffer remains available.
Relevant APIs:
@@ -225,7 +227,7 @@ function unmount() {
}
```
-If the framework already controls when frames should render, combine that with `t.noLoop()` and `t.redraw()`.
+If the framework must also guarantee deterministic shared-context ordering, use the advanced `t.noLoop()` and `t.redraw()` coordination pattern described above.
## Which path to prefer
@@ -245,7 +247,6 @@ Most of the examples below use the [`textmode.overlay.js`](/api/textmode.overlay
-
## Related APIs