|
| 1 | +--- |
| 2 | +title: Render Texture |
| 3 | +description: Off-screen rendering with RenderTexture in ESEngine |
| 4 | +--- |
| 5 | + |
| 6 | +import { Aside } from '@astrojs/starlight/components'; |
| 7 | + |
| 8 | +A **RenderTexture** lets you render a scene (or part of it) to an off-screen texture instead of the screen. This is useful for minimaps, mirrors, portals, post-processing inputs, and any effect that requires capturing rendered output. |
| 9 | + |
| 10 | +## Creating a RenderTexture |
| 11 | + |
| 12 | +```typescript |
| 13 | +import { RenderTexture, type RenderTextureHandle } from 'esengine'; |
| 14 | + |
| 15 | +const rt: RenderTextureHandle = RenderTexture.create({ |
| 16 | + width: 512, |
| 17 | + height: 512, |
| 18 | + depth: true, |
| 19 | + filter: 'linear', |
| 20 | +}); |
| 21 | +``` |
| 22 | + |
| 23 | +### RenderTextureOptions |
| 24 | + |
| 25 | +| Field | Type | Default | Description | |
| 26 | +|-------|------|---------|-------------| |
| 27 | +| `width` | `number` | — | Texture width in pixels | |
| 28 | +| `height` | `number` | — | Texture height in pixels | |
| 29 | +| `depth` | `boolean` | `false` | Attach a depth buffer | |
| 30 | +| `filter` | `'nearest' \| 'linear'` | `'nearest'` | Texture filtering mode | |
| 31 | + |
| 32 | +## Rendering to Texture |
| 33 | + |
| 34 | +Wrap your draw calls between `begin()` and `end()`. Everything rendered in between goes to the texture instead of the screen: |
| 35 | + |
| 36 | +```typescript |
| 37 | +import { RenderTexture, Draw } from 'esengine'; |
| 38 | + |
| 39 | +RenderTexture.begin(rt, viewProjectionMatrix); |
| 40 | + |
| 41 | +Draw.rect(0, 0, 100, 100, { r: 1, g: 0, b: 0, a: 1 }); |
| 42 | + |
| 43 | +RenderTexture.end(); |
| 44 | +``` |
| 45 | + |
| 46 | +The `viewProjection` parameter is a `Float32Array` containing the 4x4 view-projection matrix that defines the camera for this off-screen render pass. |
| 47 | + |
| 48 | +<Aside type="note"> |
| 49 | + `begin()` sets the render target and viewport. `end()` restores the previous render target. Always call `end()` after `begin()`. |
| 50 | +</Aside> |
| 51 | + |
| 52 | +## Using the Result |
| 53 | + |
| 54 | +After rendering, `rt.textureId` holds the GPU texture ID. Use it anywhere a texture is expected: |
| 55 | + |
| 56 | +```typescript |
| 57 | +import { Draw, Sprite } from 'esengine'; |
| 58 | + |
| 59 | +Draw.texture(rt.textureId, 0, 0, rt.width, rt.height); |
| 60 | +``` |
| 61 | + |
| 62 | +You can also assign it to a Sprite's texture for entity-based rendering. |
| 63 | + |
| 64 | +## Depth Texture |
| 65 | + |
| 66 | +If the RenderTexture was created with `depth: true`, retrieve the depth texture for effects like shadow mapping: |
| 67 | + |
| 68 | +```typescript |
| 69 | +const depthTextureId = RenderTexture.getDepthTexture(rt); |
| 70 | +``` |
| 71 | + |
| 72 | +## Lifecycle |
| 73 | + |
| 74 | +### Resizing |
| 75 | + |
| 76 | +When the target resolution changes (e.g. window resize), resize the RenderTexture: |
| 77 | + |
| 78 | +```typescript |
| 79 | +const resized = RenderTexture.resize(rt, newWidth, newHeight); |
| 80 | +``` |
| 81 | + |
| 82 | +`resize()` returns a new `RenderTextureHandle`. Use the returned handle going forward. |
| 83 | + |
| 84 | +### Releasing |
| 85 | + |
| 86 | +Release GPU resources when the RenderTexture is no longer needed: |
| 87 | + |
| 88 | +```typescript |
| 89 | +RenderTexture.release(rt); |
| 90 | +``` |
| 91 | + |
| 92 | +## API Reference |
| 93 | + |
| 94 | +| Method | Returns | Description | |
| 95 | +|--------|---------|-------------| |
| 96 | +| `RenderTexture.create(options)` | `RenderTextureHandle` | Create a new render texture | |
| 97 | +| `RenderTexture.begin(rt, viewProjection)` | `void` | Begin rendering to texture | |
| 98 | +| `RenderTexture.end()` | `void` | End rendering to texture | |
| 99 | +| `RenderTexture.getDepthTexture(rt)` | `number` | Get depth texture ID | |
| 100 | +| `RenderTexture.resize(rt, width, height)` | `RenderTextureHandle` | Resize render texture | |
| 101 | +| `RenderTexture.release(rt)` | `void` | Release GPU resources | |
| 102 | + |
| 103 | +### RenderTextureHandle |
| 104 | + |
| 105 | +| Field | Type | Description | |
| 106 | +|-------|------|-------------| |
| 107 | +| `textureId` | `number` | GPU texture ID for the color attachment | |
| 108 | +| `width` | `number` | Current width in pixels | |
| 109 | +| `height` | `number` | Current height in pixels | |
| 110 | + |
| 111 | +## Next Steps |
| 112 | + |
| 113 | +- [Custom Draw](/microes/guides/custom-draw/) — immediate-mode drawing API |
| 114 | +- [Post-Processing](/microes/guides/post-processing/) — full-screen effects |
| 115 | +- [Materials & Shaders](/microes/guides/materials/) — custom shaders |
0 commit comments