luma.gl/docs/api-reference-legacy/classes/renderbuffer.md

# Renderbuffer

> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.

`Renderbuffer`s are WebGL Objects that contain textures. They are optimized for use as render targets, while vanilla `Texture`s may not be, and are the logical choice when you do not need to sample (i.e. in a post-pass shader) from the produced image. If you do need to sample (such as when reading depth back in a second shader pass), use [`Texture`](/docs/api-reference/webgl/texture) instead. In addition, in WebGL 2, `Renderbuffer` can do [Multisampling (MSAA)](https://www.khronos.org/opengl/wiki/Multisampling) just like standard framebuffer.

For additional information, see [OpenGL Wiki](https://www.opengl.org/wiki/Renderbuffer_Object)

## Usage

Creating a `Renderbuffer`

```js
const renderbuffer = new Renderbuffer(gl, {format: GL.RGBA4, width: 100, height: 100});
```

Reformatting/reinitializing a `Renderbuffer`

```js
const renderbuffer = new Renderbuffer(gl, {format: GL.RGBA4, width: 100, height: 100});
renderbuffer.initialize({format: GL.RGB565, width: 50, height: 50});
```

Resizing a `Renderbuffer`

```js
const renderbuffer = new Renderbuffer(gl, {format: GL.RGBA4});
renderbuffer.resize({width: 200, height: 200});
```

Attaching a `Renderbuffer` to a `Framebuffer` (automatically resizes the `Renderbuffer`)

```js
framebuffer.attach({
  [GL.DEPTH_ATTACHMENT]: new Renderbuffer(gl, {format: GL.DEPTH_COMPONENT16})
});
```

## Members

- `id` (string) - id for debugging
- `handle` (`WebGLRenderbuffer`) - the underlying WebGLRenderbuffer object
- `width` (number) - width of renderbuffer in pixels
- `height` (number) - height of renderbuffer in pixels
- `format` (number) - internal format of the renderbuffer (e.g. `GL.DEPTH_COMPONENT16`)
- `samples` (number) - samples (always `0` in non-WebGL 2 contexts)

## Methods

### getSamplesForFormat (static method)

Queries valid sample counts for a `Renderbuffer` format. The sample counts can be provided as a parameter to the `Renderbuffer` constructor.

`Renderbuffer.getSamplesForFormat({format})`

- `format` (GLenum) - internal format of the renderbuffer (e.g. `GL.DEPTH_COMPONENT16`)

Returns (Number[]) - An list of valid sample counts in descending order.

If multisampling is not supported the returned value will be `[0]`, e.g. signed and unsigned integer internal formats in WebGL 2. Note that this method always returns `[0]` in WebGL 1.

### constructor

Creates a new `Renderbuffer` and initalizes it by calling `initialize` with the provided parameters.

`new Renderbuffer(gl, {id=, format, width, height, samples=})`

- `gl` (WebGLRenderingContext) - gl context
- `id`= (String) - optional string id
- `format` (GLenum) - internal format of the renderbuffer (e.g. `GL.DEPTH_COMPONENT16`)
- `width`=`1` (GLint) - width of renderbuffer in pixels
- `height`=`1` (GLint) - height of renderbuffer in pixels
- `samples`=0 (GLint) - (WebGL 2) number of samples to be used for storage.

WebGL References [gl.createRenderbuffer](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createRenderbuffer), also see `initialize`.

### initialize

Creates and initializes a renderbuffer object's data store. Used to update a `Renderbuffer`s format and size after it was initially created.

`Renderbuffer.initialize({format, width, height, samples=})`

- `format` (GLenum) - internal format of the renderbuffer (e.g. `GL.DEPTH_COMPONENT16`)
- `width`=`1` (GLint) - width of renderbuffer in pixels
- `height`=`1` (GLint) - height of renderbuffer in pixels
- `samples`=0 (GLint) - (WebGL 2) number of samples to be used for storage.

Returns itself to enable chaining

- `initialize` erases the current content of the `Renderbuffer`.

WebGL References [gl.renderbufferStorage](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/renderbufferStorage), [gl.renderbufferStorageMultisample](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/renderbufferStorageMultisample) (WebGL 2), [gl.bindRenderbuffer](<WebGLRenderingContext.bindRenderbuffer()>)

### resize

Reinitializes the `Renderbuffer`'s data store with the new `width` and `height` but unchanged `format` (and `samples`, if available).

`Renderbuffer.resize({width, height})`

- `width` (GLint) - width of `Renderbuffer` in pixels
- `height` (GLint) - height of `Renderbuffer` in pixels

Returns itself to enable chaining

- Checks if `width` or `height` have actually changed before calling `initialize`.
- If a resize happens, `resize` erases the current content of the `Renderbuffer`.

WebGL References see `initialize`.

## Renderbuffer Formats

The "internal" format of the `Renderbuffer`.

| Value                  | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `GL.RGBA4`             | 4 red bits, 4 green bits, 4 blue bits 4 alpha bits |
| `GL.RGB565`            | 5 red bits, 6 green bits, 5 blue bits              |
| `GL.RGB5_A1`           | 5 red bits, 5 green bits, 5 blue bits, 1 alpha bit |
| `GL.DEPTH_COMPONENT16` | 16 depth bits                                      |
| `GL.STENCIL_INDEX8`    | 8 stencil bits                                     |

This table lists the basic formats supported in WebGL 1. For a full table of formats supported in WebGL 2 and via WebGL extensions, see [Texture](/docs/api-reference/webgl/texture).

| Sized Internal Format   | Format               | Type                                   | Depth Bits | Stencil Bits |
| ----------------------- | -------------------- | -------------------------------------- | ---------- | ------------ |
| `GL.DEPTH_COMPONENT16`  | `GL.DEPTH_COMPONENT` | `GL.UNSIGNED_SHORT`, `GL.UNSIGNED_INT` | 16         | 0            |
| `GL.DEPTH_COMPONENT24`  | `GL.DEPTH_COMPONENT` | `GL.UNSIGNED_INT`                      | 24         | 0            |
| `GL.DEPTH_COMPONENT32F` | `GL.DEPTH_COMPONENT` | `GL.FLOAT`                             | f32        | 0            |
| `GL.DEPTH24_STENCIL8`   | `GL.DEPTH_STENCIL`   | `GL.UNSIGNED_INT_24_8`                 | 24         | 8            |
| `GL.DEPTH32F_STENCIL8`  | `GL.DEPTH_STENCIL`   | `GL.FLOAT_32_UNSIGNED_INT_24_8_REV`    | f32        | 8            |

When using the WEBGL_depth_texture extension:
`GL.DEPTH_COMPONENT`
`GL.DEPTH_STENCIL`
When using the EXT_sRGB extension:
`EXT.SRGB_EXT`
`EXT.SRGB_ALPHA_EXT`

When using a WebGL 2 context, the following values are available additionally:

- `GL.R8`
- `GL.R16F`
- `GL.R32F`
- `GL.R8UI`
- `GL.RG8`
- `GL.RG16F`
- `GL.RG32F`
- `GL.RGUI`
- `GL.RGB8`
- `GL.SRGB8`
- `GL.RGB565`
- `GL.R11F_G11F_B10F`
- `GL.RGB9_E5`
- `GL.RGB16F`
- `GL.RGB32F`
- `GL.RGB8UI`
- `GL.RGBA8`
- `GL.SRGB_APLHA8`
- `GL.RGB5_A1`
- `GL.RGBA4444`
- `GL.RGBA16F`
- `GL.RGBA32F`
- `GL.RGBA8UI`

## Parameters

| Parameter                           | Type   | Read/Write | Description                            |
| ----------------------------------- | ------ | ---------- | -------------------------------------- |
| `GL.RENDERBUFFER_WIDTH`             | GLint  | R          | height of the image of renderbuffer    |
| `GL.RENDERBUFFER_HEIGHT`            | GLint  | R          | height of the image of renderbuffer    |
| `GL.RENDERBUFFER_INTERNAL_FORMAT`   | GLenum | R          | See below                              |
| `GL.RENDERBUFFER_GREEN_SIZE`        | GLint  | R          | resolution (bits) of green color       |
| `GL.RENDERBUFFER_BLUE_SIZE`         | GLint  | R          | resolution (bits) of blue color        |
| `GL.RENDERBUFFER_RED_SIZE`          | GLint  | R          | resolution (bits) of red color         |
| `GL.RENDERBUFFER_ALPHA_SIZE`        | GLint  | R          | resolution (bits) of alpha component   |
| `GL.RENDERBUFFER_DEPTH_SIZE`        | GLint  | R          | resolution (bits) of depth component   |
| `GL.RENDERBUFFER_STENCIL_SIZE`      | GLint  | R          | resolution (bits) of stencil component |
| `GL.RENDERBUFFER_SAMPLES` (WebGL 2) | GLint  | R          |                                        |

## Limits

| Limit                      |                               | WebGL 2  | WebGL 1 |
| -------------------------- | ----------------------------- | -------- | ------- |
| `GL.MAX_RENDERBUFFER_SIZE` | Max renderbuffer width/height | `>=2048` | `>=1`   |
| `GL.MAX_SAMPLES`           | Max samples for multisampling | `>=4`    | `0`     |

## Remarks

- The only way to work with a renderbuffer, besides creating it, is to attach it to a [`Framebuffer`](/docs/api-reference/webgl/framebuffer).
- A `Renderbuffer` cannot be accessed by a shader in any way.
- Multisampling is only available in WebGL 2