feat: add SDL2::Renderer#read_pixels

[takaokouji]

Summary

Add SDL2::Renderer#read_pixels method that wraps SDL_RenderReadPixels.

This enables reading pixel data from the current rendering target, which is essential for taking screenshots of the rendered screen.

Usage

# Read the entire screen (ARGB8888 format)
pixels = renderer.read_pixels(nil, 0)

# Read a specific area
rect = SDL2::Rect.new(0, 0, 100, 100)
pixels = renderer.read_pixels(rect, 0)

Parameters

• rect — SDL2::Rect or nil (nil reads the entire target)
• format — pixel format as Integer (0 defaults to SDL_PIXELFORMAT_ARGB8888)

Returns

Raw pixel data as a binary String.

Motivation

As noted in #28, there is currently no way to capture screen contents for screenshots. This method provides the missing functionality by wrapping SDL_RenderReadPixels.

Closes #28

[ohai]

Thank you for your PR.
Would you give me a sample Ruby program to demonstrate the new method?

[takaokouji]

Thank you for reviewing!

Here is a real-world usage from Smalruby. We use read_pixels to capture the SDL2 window contents for debugging screenshots:

https://github.com/smalruby/smalruby3-editor/blob/77c82085940532d7b7097b3afe8686134c131261/ruby/smalruby3/lib/smalruby3/render/renderer.rb#L229

Here is a standalone sample program that saves the rendered screen as a BMP file (no extra image library needed):

require "sdl2"

SDL2.init(SDL2::INIT_VIDEO)
window = SDL2::Window.create("read_pixels demo", 100, 100, 320, 240, 0)
renderer = window.create_renderer(-1, 0)

# Draw something
renderer.draw_color = [0, 128, 255]
renderer.fill_rect(SDL2::Rect.new(60, 40, 200, 160))
renderer.draw_color = [255, 255, 0]
renderer.fill_rect(SDL2::Rect.new(110, 80, 100, 80))
renderer.present

# Capture the rendered pixels (ARGB8888, little-endian → BGRA bytes)
pixels = renderer.read_pixels(nil, 0)

# Save as BMP
width, height = 320, 240
row_size = width * 4
file_size = 54 + row_size * height
bmp = String.new(encoding: Encoding::BINARY)
bmp << ["BM", file_size, 0, 0, 54].pack("A2Vv2V")           # file header
bmp << [40, width, height, 1, 32, 0, 0, 0, 0, 0, 0].pack("VV2v2V6") # DIB header
# BMP stores rows bottom-to-top; pixel data is already BGRA which BMP expects
(height - 1).downto(0) do |y|
  bmp << pixels.byteslice(y * row_size, row_size)
end
File.binwrite("screenshot.bmp", bmp)
puts "Saved screenshot.bmp (#{File.size("screenshot.bmp")} bytes)"

PNG conversion requires an image utility library, so I used BMP here to keep the example dependency-free.

[ohai]

After the assessment of the patch, I have concluded that the quality is not satisfactory:

• The new method does not accept SDL2::PixelFormat
• The default pixel format is not ARGB8888. See https://wiki.libsdl.org/SDL2/SDL_RenderReadPixels
• The attached sample code does not work as intended in some environments, such as Wayland on Linux. See the above official document.

[takaokouji]

Thank you for the detailed review. I have addressed all three points and resubmitted as #31:

1. SDL2::PixelFormat support — The format parameter now accepts both SDL2::PixelFormat and Integer, using uint32_for_format() (consistent with create_texture etc.)
2. Default pixel format — Removed the ARGB8888 override. Passing 0 now correctly uses the rendering target's native format as defined by SDL2.
3. Sample program — Included sample/test_read_pixels.rb which explicitly specifies SDL2::PixelFormat::ARGB8888 to ensure consistent behavior across platforms.

Would you please review #31 when you have a chance?