---
name: "glReadPixels"
section: "3x"
platform: "linux"
package: "xlibmesa-gl-dev"
version: "4.3.0.dfsg.1-14sarge7"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/glReadPixels"
---

# glReadPixels(3x)

read a block of pixels from the frame buffer

## NAME

**glReadPixels** - read a block of pixels from the frame buffer

## C SPECIFICATION

void **glReadPixels**( GLint *x*,

```
	GLint y,
	GLsizei width,
	GLsizei height,
	GLenum format,
	GLenum type,
	GLvoid *pixels )
```

delim $$

## PARAMETERS

- *x*, *y*

  Specify the window coordinates of the first pixel that is read from the frame buffer. This location is the lower left corner of a rectangular block of pixels.

- *width*, *height*

  Specify the dimensions of the pixel rectangle. *width* and *height* of one correspond to a single pixel.

- *format*

  Specifies the  of the pixel data. The following symbolic values are accepted: **GL\_COLOR\_INDEX**, **GL\_STENCIL\_INDEX**, **GL\_DEPTH\_COMPONENT**, **GL\_RED**, **GL\_GREEN**, **GL\_BLUE**, **GL\_ALPHA**, **GL\_RGB**, **GL\_BGR**, **GL\_RGBA**, **GL\_BGRA**, **GL\_LUMINANCE**, and **GL\_LUMINANCE\_ALPHA**.

- *type*

  Specifies the data type of the pixel data. Must be one of **GL\_UNSIGNED\_BYTE**, **GL\_BYTE**, **GL\_BITMAP**, **GL\_UNSIGNED\_SHORT**, **GL\_SHORT**, **GL\_UNSIGNED\_INT**, **GL\_INT**, **GL\_FLOAT**, **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, or **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV**.

- *pixels*

  Returns the pixel data.

## DESCRIPTION

**glReadPixels** returns pixel data from the frame buffer, starting with the pixel whose lower left corner is at location (*x*, *y*), into client memory starting at location *pixels*. Several parameters control the processing of the pixel data before it is placed into client memory. These parameters are set with three commands: **glPixelStore**, **glPixelTransfer**, and **glPixelMap**. This reference page describes the effects on **glReadPixels** of most, but not all of the parameters specified by these three commands.

When the **GL\_ARB\_imaging** extension is supported, the pixel data may be processed by additional operations including color table lookup, color matrix transformations, convolutions, histograms and minimum and maximun pixel value computations.

**glReadPixels** returns values from each pixel with lower left corner at (*x* + $i$, *y* + $j$) for 0 ≤ $i$ \< *width* and  0 ≤ $j$ \< *height*. This pixel is said to be the $i$th pixel in the $j$th row.  Pixels are returned in row order from the lowest to the highest row, left to right in each row.

*format* specifies the  for the returned pixel values; accepted values are:

- **GL\_COLOR\_INDEX**

  Color indices are read from the color buffer selected by **glReadBuffer**. Each index is converted to fixed point, shifted left or right depending on the value and sign of **GL\_INDEX\_SHIFT**, and added to **GL\_INDEX\_OFFSET**.  If **GL\_MAP\_COLOR** is **GL\_TRUE**, indices are replaced by their mappings in the table **GL\_PIXEL\_MAP\_I\_TO\_I**.

- **GL\_STENCIL\_INDEX**

  Stencil values are read from the stencil buffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of **GL\_INDEX\_SHIFT**, and added to **GL\_INDEX\_OFFSET**.  If **GL\_MAP\_STENCIL** is **GL\_TRUE**, indices are replaced by their mappings in the table **GL\_PIXEL\_MAP\_S\_TO\_S**.

- **GL\_DEPTH\_COMPONENT**

  Depth values are read from the depth buffer. Each component is converted to floating point such that the minimum depth value maps to 0 and the maximum value maps to 1. Each component is then multiplied by **GL\_DEPTH\_SCALE**, added to **GL\_DEPTH\_BIAS**, and finally clamped to the range \[0,1\].

- **GL\_RED**

  - **GL\_GREEN**

  - **GL\_BLUE**

  - **GL\_ALPHA**

  - **GL\_RGB**

  - **GL\_BGR**

  - **GL\_RGBA**

  - **GL\_BGRA**

  - **GL\_LUMINANCE**

  - **GL\_LUMINANCE\_ALPHA**

  Processing differs depending on whether color buffers store color indices or RGBA color components. If color indices are stored, they are read from the color buffer selected by **glReadBuffer**. Each index is converted to fixed point, shifted left or right depending on the value and sign of **GL\_INDEX\_SHIFT**, and added to **GL\_INDEX\_OFFSET**.  Indices are then replaced by the red, green, blue, and alpha values obtained by indexing the tables **GL\_PIXEL\_MAP\_I\_TO\_R**, **GL\_PIXEL\_MAP\_I\_TO\_G**, **GL\_PIXEL\_MAP\_I\_TO\_B**, and **GL\_PIXEL\_MAP\_I\_TO\_A**. Each table must be of size $2 sup n$, but $n$ may be different for  different tables.  Before an index is used to look up a value in a table of size $2 sup n$, it must be masked against $2 sup n - 1$.

-

  If RGBA color components are stored in the color buffers, they are read from the color buffer selected by **glReadBuffer**. Each color component is converted to floating point such that zero intensity maps to 0.0 and full intensity maps to 1.0. Each component is then multiplied by **GL\_c\_SCALE** and added to **GL\_c\_BIAS**, where *c* is RED, GREEN, BLUE, or ALPHA.  Finally, if **GL\_MAP\_COLOR** is **GL\_TRUE**, each component is clamped to the range \[0, 1\], scaled to the size of its corresponding table, and is then  replaced by its mapping in the table **GL\_PIXEL\_MAP\_c\_TO\_c**, where *c* is R, G, B, or A.

-

  Unneeded data is then discarded. For example, **GL\_RED** discards the green, blue, and alpha components, while **GL\_RGB** discards only the alpha component. **GL\_LUMINANCE** computes a single-component value as the sum of the red, green, and blue components, and **GL\_LUMINANCE\_ALPHA** does the same, while keeping alpha as a second value. The final values are clamped to the range \[0, 1\].

The shift, scale, bias, and lookup factors just described are all specified by \
 **glPixelTransfer**. The lookup table contents themselves are specified by **glPixelMap**.

Finally, the indices or components are converted to the proper , as specified by *type*. If *format* is **GL\_COLOR\_INDEX** or **GL\_STENCIL\_INDEX** and *type* is not **GL\_FLOAT**, each index is masked with the mask value given in the following table. If *type* is **GL\_FLOAT**, then each integer index is converted to single-precision floating-point .

If *format* is **GL\_RED**, **GL\_GREEN**, **GL\_BLUE**, **GL\_ALPHA**, **GL\_RGB**, **GL\_BGR**, **GL\_RGBA**, **GL\_BGRA**, **GL\_LUMINANCE**, or **GL\_LUMINANCE\_ALPHA** and *type* is not **GL\_FLOAT**, each component is multiplied by the multiplier shown in the following table. If type is **GL\_FLOAT**, then each component is passed as is (or converted to the client's single-precision floating-point  if it is different from the one used by the GL).

| | | |
| --- | --- | --- |
| *type* | **index mask** | **component conversion** |
| **GL\_UNSIGNED\_BYTE** | $2"^"8 - 1$ | $(2"^"8 - 1) c$ |
| **GL\_BYTE** | $2"^"7 - 1$ | $\[(2"^"8 - 1) c - 1\] / 2$ |
| **GL\_BITMAP** | $1$ | $1$ |
| **GL\_UNSIGNED\_SHORT** | $2"^"16 - 1$ | $(2"^"16 - 1) c$ |
| **GL\_SHORT** | $2"^"15 - 1$ | $\[(2"^"16 - 1) c - 1\] / 2$ |
| **GL\_UNSIGNED\_INT** | $2"^"32 - 1$ | $(2"^"32 - 1) c$ |
| **GL\_INT** | $2"^"31 - 1$ | $\[(2"^"32 - 1) c - 1\] / 2$ |
| **GL\_FLOAT** | none | $c$ |

Return values are placed in memory as follows. If *format* is **GL\_COLOR\_INDEX**, **GL\_STENCIL\_INDEX**, **GL\_DEPTH\_COMPONENT**, **GL\_RED**, **GL\_GREEN**, **GL\_BLUE**, **GL\_ALPHA**, or  **GL\_LUMINANCE**, a single value is returned and the data for the $i$th pixel in the $j$th row is placed in location $(j)~"width"~+~i$. **GL\_RGB** and **GL\_BGR** return three values, **GL\_RGBA** and **GL\_BGRA** return four values, and **GL\_LUMINANCE\_ALPHA** returns two values for each pixel, with all values corresponding to a single pixel occupying contiguous space in *pixels*. Storage parameters set by **glPixelStore**, such as **GL\_PACK\_LSB\_FIRST** and **GL\_PACK\_SWAP\_BYTES**, affect the way that data is written into memory. See **glPixelStore** for a description.

## NOTES

Values for pixels that lie outside the window connected to the current GL context are undefined.

If an error is generated, no change is made to the contents of *pixels*.

## ERRORS

**GL\_INVALID\_ENUM** is generated if *format* or *type* is not an accepted value.

**GL\_INVALID\_ENUM** is generated if *type* is **GL\_BITMAP** and *format* is not **GL\_COLOR\_INDEX** or **GL\_STENCIL\_INDEX**.

**GL\_INVALID\_VALUE** is generated if either *width* or *height* is negative.

**GL\_INVALID\_OPERATION** is generated if *format* is **GL\_COLOR\_INDEX** and the color buffers store RGBA color components.

**GL\_INVALID\_OPERATION** is generated if *format* is **GL\_STENCIL\_INDEX** and there is no stencil buffer.

**GL\_INVALID\_OPERATION** is generated if *format* is **GL\_DEPTH\_COMPONENT** and there is no depth buffer.

**GL\_INVALID\_OPERATION** is generated if **glReadPixels** is executed between the execution of **glBegin** and the corresponding execution of **glEnd**.

**GL\_INVALID\_OPERATION** is generated if *type* is one of **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, or **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV** and *format* is not **GL\_RGB**.

**GL\_INVALID\_OPERATION** is generated if *type* is one of **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, or **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV** and *format* is neither **GL\_RGBA** nor **GL\_BGRA**.

The formats **GL\_BGR**, and **GL\_BGRA** and types  **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, and **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV** are available only if the GL version  is 1.2 or greater.

## ASSOCIATED GETS

**glGet** with argument **GL\_INDEX\_MODE**

## SEE ALSO

**glCopyPixels(3G)**, **glDrawPixels(3G)**, **glPixelMap(3G)**, **glPixelStore(3G)**, **glPixelTransfer(3G)**,\
 **glReadBuffer(3G)**