Wiki Page Content

Differences between revisions 14 and 16 (spanning 2 versions)
Revision 14 as of 2020-04-21 17:58:11
Size: 1762
Editor: ChrisBush
Comment: Clarify 'pitch' parameter per feedback form
Revision 16 as of 2020-04-29 20:50:08
Size: 1943
Editor: DanielG
Comment: mention potential padding in pitch
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
Use this function to read pixels from the current rendering target. Use this function to read pixels from the current rendering target to an array of pixels.
Line 22: Line 22:
||'''pixels'''||a pointer filled in with the pixel data|| ||'''pixels'''||a pointer to the pixel data to copy into||
Line 36: Line 36:
<<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).
Line 39: Line 43:
<<Anchor(pitch)>> '''pitch''' specifies the number of bytes between rows of pixels.
This allows you to use a subrectangle of a larger pixels array or have padded rows in the pixel data.
Generally, this should equal the number of pixels per row of pixel data times the number of bytes per pixel.

SDL_RenderReadPixels

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

Syntax

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 Remarks for details

pixels

a pointer to the pixel data to copy into

pitch

the pitch of the pixels parameter; see Remarks for details

Return Value

Returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

Code Examples

You can add your code example here

Remarks

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

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).

format may be one of the following:

SDL_PIXELFORMAT_UNKNOWN

SDL_PIXELFORMAT_INDEX1LSB

SDL_PIXELFORMAT_INDEX1MSB

SDL_PIXELFORMAT_INDEX4LSB

SDL_PIXELFORMAT_INDEX4MSB

SDL_PIXELFORMAT_INDEX8

SDL_PIXELFORMAT_RGB332

SDL_PIXELFORMAT_RGB444

SDL_PIXELFORMAT_RGB555

SDL_PIXELFORMAT_BGR555

SDL_PIXELFORMAT_ARGB4444

SDL_PIXELFORMAT_RGBA4444

SDL_PIXELFORMAT_ABGR4444

SDL_PIXELFORMAT_BGRA4444

SDL_PIXELFORMAT_ARGB1555

SDL_PIXELFORMAT_RGBA5551

SDL_PIXELFORMAT_ABGR1555

SDL_PIXELFORMAT_BGRA5551

SDL_PIXELFORMAT_RGB565

SDL_PIXELFORMAT_BGR565

SDL_PIXELFORMAT_RGB24

SDL_PIXELFORMAT_BGR24

SDL_PIXELFORMAT_RGB888

SDL_PIXELFORMAT_RGBX8888

SDL_PIXELFORMAT_BGR888

SDL_PIXELFORMAT_BGRX8888

SDL_PIXELFORMAT_ARGB8888

SDL_PIXELFORMAT_RGBA8888

SDL_PIXELFORMAT_ABGR8888

SDL_PIXELFORMAT_BGRA8888

SDL_PIXELFORMAT_ARGB2101010

SDL_PIXELFORMAT_RGBA32

alias for RGBA byte array of color data, for the current platform (>= SDL 2.0.5)

SDL_PIXELFORMAT_ARGB32

alias for ARGB byte array of color data, for the current platform (>= SDL 2.0.5)

SDL_PIXELFORMAT_BGRA32

alias for BGRA byte array of color data, for the current platform (>= SDL 2.0.5)

SDL_PIXELFORMAT_ABGR32

alias for ABGR byte array of color data, for the current platform (>= SDL 2.0.5)

SDL_PIXELFORMAT_YV12

planar mode: Y + V + U (3 planes)

SDL_PIXELFORMAT_IYUV

planar mode: Y + U + V (3 planes)

SDL_PIXELFORMAT_YUY2

packed mode: Y0+U0+Y1+V0 (1 plane)

SDL_PIXELFORMAT_UYVY

packed mode: U0+Y0+V0+Y1 (1 plane)

SDL_PIXELFORMAT_YVYU

packed mode: Y0+V0+Y1+U0 (1 plane)

SDL_PIXELFORMAT_NV12

planar mode: Y + U/V interleaved (2 planes) (>= SDL 2.0.4)

SDL_PIXELFORMAT_NV21

planar mode: Y + V/U interleaved (2 planes) (>= SDL 2.0.4)


CategoryAPI, CategoryRender

None: SDL_RenderReadPixels (last edited 2020-04-29 20:50:08 by DanielG)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit