#pragma section-numbers off
#pragma disable-camelcase

= SDL_RenderReadPixels =
Use this function to read pixels from the current rendering target to an array of pixels.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
int SDL_RenderReadPixels(SDL_Renderer*   renderer,
                         const SDL_Rect* rect,
                         Uint32          format,
                         void*           pixels,
                         int             pitch)
}}}

== Function Parameters ==
||'''renderer'''||the rendering context||
||'''rect'''||an [[SDL_Rect]] structure representing the area to read, or NULL for the entire render target||
||'''format'''||the desired format of the pixel data, or 0 to use the format of the rendering target; see [[#format|Remarks]] for details||
||'''pixels'''||a pointer to the pixel data to copy into||
||'''pitch'''||the pitch of the '''pixels''' parameter; see [[#pitch|Remarks]] for details||

== Return Value ==
Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
You can add your code example here
}}}

== Remarks ==
/!\ WARNING: This is a very slow operation, and should not be used frequently.

<<Anchor(pitch)>> '''pitch''' specifies the number of bytes between rows in the destination '''pixels''' data.
This allows you to write to a subrectangle or have padded rows in the destination.
Generally, '''pitch''' should equal the ''number of pixels per row'' in the '''pixels''' data times the ''number of bytes per pixel'', but it might contain additional padding (for example, 24bit RGB Windows Bitmap data pads all rows to multiples of 4 bytes).

<<Anchor(format)>> '''format''' may be one of the following:
<<Include(SDL_PixelFormatEnum, , , from="=== Pixel Format Values ===", to="== Code Examples ==")>>

----
[[CategoryAPI]], [[CategoryRender]]