Teek::SDL2::Renderer | Teek API Documentation

GPU-accelerated 2D renderer backed by SDL2.

Renderer wraps an SDL_Renderer and provides both low-level positional-arg methods (defined in C) and higher-level Ruby convenience wrappers with keyword arguments.

You don’t create a Renderer directly — it’s created automatically by Viewport and accessible via Viewport#renderer.

C-defined methods

These are defined in the C extension (sdl2surface.c) and available on every Renderer instance:

#clear — clear the rendering target
#present — flip the back buffer to screen
#fill_rect — draw a filled rectangle
#draw_rect — draw a rectangle outline
#draw_line — draw a line
#copy — copy a texture to the rendering target
#create_texture — create a new texture
#output_size — query the renderer output dimensions
#destroy — destroy the renderer
#destroyed? — check if the renderer has been destroyed

Inherits: Object

Instance Methods ↑

blit(texture, src: nil, dst: nil)

Copy a texture (keyword-arg wrapper for #copy).

Parameters

texture Texture — the source texture
src Array(Integer, Integer, Integer, Integer), nil — source rectangle [x, y, w, h] or nil for entire texture
dst Array(Integer, Integer, Integer, Integer), nil — destination rectangle [x, y, w, h] or nil for entire target

Returns self

View source ▼

def blit(texture, src: nil, dst: nil)
  copy(texture, src, dst)
end

clear(r 0, g 0, b 0, a 255)

Clear the entire rendering target with the given color.

Parameters

r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

static VALUE
renderer_clear(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    Uint8 r = 0, g = 0, b = 0, a = 255;

    if (argc > 0) r = (Uint8)NUM2INT(argv[0]);
    if (argc > 1) g = (Uint8)NUM2INT(argv[1]);
    if (argc > 2) b = (Uint8)NUM2INT(argv[2]);
    if (argc > 3) a = (Uint8)NUM2INT(argv[3]);

    SDL_SetRenderDrawColor(ren->renderer, r, g, b, a);
    SDL_RenderClear(ren->renderer);
    return self;
}

copy(texture, src_rect nil, dst_rect nil)

Copy a texture (or portion of it) to the rendering target.

Parameters

texture Texture — the source texture
src_rect Array(Integer, Integer, Integer, Integer), nil — source rectangle [x, y, w, h] or nil for entire texture
dst_rect Array(Integer, Integer, Integer, Integer), nil — destination rectangle [x, y, w, h] or nil for entire target

Returns self

View source ▼

static VALUE
renderer_copy(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    VALUE tex_obj, src_rect_obj, dst_rect_obj;
    SDL_Rect src, dst, *srcp = NULL, *dstp = NULL;

    rb_scan_args(argc, argv, "12", &tex_obj, &src_rect_obj, &dst_rect_obj);

    struct sdl2_texture *t = get_texture(tex_obj);

    if (!NIL_P(src_rect_obj)) {
        Check_Type(src_rect_obj, T_ARRAY);
        src.x = NUM2INT(rb_ary_entry(src_rect_obj, 0));
        src.y = NUM2INT(rb_ary_entry(src_rect_obj, 1));
        src.w = NUM2INT(rb_ary_entry(src_rect_obj, 2));
        src.h = NUM2INT(rb_ary_entry(src_rect_obj, 3));
        srcp = &src;
    }

    if (!NIL_P(dst_rect_obj)) {
        Check_Type(dst_rect_obj, T_ARRAY);
        dst.x = NUM2INT(rb_ary_entry(dst_rect_obj, 0));
        dst.y = NUM2INT(rb_ary_entry(dst_rect_obj, 1));
        dst.w = NUM2INT(rb_ary_entry(dst_rect_obj, 2));
        dst.h = NUM2INT(rb_ary_entry(dst_rect_obj, 3));
        dstp = &dst;
    }

    if (SDL_RenderCopy(ren->renderer, t->texture, srcp, dstp) != 0) {
        rb_raise(eSDL2Error, "SDL_RenderCopy: %s", SDL_GetError());
    }
    return self;
}

create_texture(width, height, access :static)

Create a new texture owned by this renderer.

Parameters

width Integer — texture width in pixels
height Integer — texture height in pixels
access Symbol — :static, :streaming, or :target

Returns Texture

View source ▼

static VALUE
renderer_create_texture(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    int w, h;
    int access = SDL_TEXTUREACCESS_STREAMING;

    rb_check_arity(argc, 2, 3);
    w = NUM2INT(argv[0]);
    h = NUM2INT(argv[1]);

    if (argc > 2 && !NIL_P(argv[2])) {
        ID sym = SYM2ID(argv[2]);
        if (sym == rb_intern("static"))
            access = SDL_TEXTUREACCESS_STATIC;
        else if (sym == rb_intern("streaming"))
            access = SDL_TEXTUREACCESS_STREAMING;
        else if (sym == rb_intern("target"))
            access = SDL_TEXTUREACCESS_TARGET;
        else
            rb_raise(rb_eArgError, "unknown access mode (use :static, :streaming, or :target)");
    }

    SDL_Texture *tex = SDL_CreateTexture(ren->renderer,
                                         SDL_PIXELFORMAT_ARGB8888,
                                         access, w, h);
    if (!tex) {
        rb_raise(eSDL2Error, "SDL_CreateTexture: %s", SDL_GetError());
    }

    VALUE obj = texture_alloc(cTexture);
    struct sdl2_texture *t;
    TypedData_Get_Struct(obj, struct sdl2_texture, &texture_type, t);
    t->texture = tex;
    t->w = w;
    t->h = h;
    t->renderer_obj = self;
    return obj;
}

destroy

Destroy this renderer and free GPU resources.

Returns void

View source ▼

static VALUE
renderer_destroy(VALUE self)
{
    struct sdl2_renderer *r;
    TypedData_Get_Struct(self, struct sdl2_renderer, &renderer_type, r);
    if (!r->destroyed) {
        if (r->renderer) {
            SDL_DestroyRenderer(r->renderer);
            r->renderer = NULL;
        }
        if (r->window && r->owned_window) {
            SDL_DestroyWindow(r->window);
            r->window = NULL;
        }
        r->destroyed = 1;
    }
    return Qnil;
}

destroyed?

Returns Boolean — whether this renderer has been destroyed

View source ▼

static VALUE
renderer_destroyed_p(VALUE self)
{
    struct sdl2_renderer *r;
    TypedData_Get_Struct(self, struct sdl2_renderer, &renderer_type, r);
    return r->destroyed ? Qtrue : Qfalse;
}

draw_line(x1, y1, x2, y2, r, g, b, a 255)

Draw a line between two points.

Parameters

x1 Integer — start x
y1 Integer — start y
x2 Integer — end x
y2 Integer — end y
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

static VALUE
renderer_draw_line(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    Uint8 r, g, b, a = 255;

    rb_check_arity(argc, 7, 8);
    r = (Uint8)NUM2INT(argv[4]);
    g = (Uint8)NUM2INT(argv[5]);
    b = (Uint8)NUM2INT(argv[6]);
    if (argc > 7) a = (Uint8)NUM2INT(argv[7]);

    SDL_SetRenderDrawBlendMode(ren->renderer, a < 255 ? SDL_BLENDMODE_BLEND : SDL_BLENDMODE_NONE);
    SDL_SetRenderDrawColor(ren->renderer, r, g, b, a);
    SDL_RenderDrawLine(ren->renderer,
                       NUM2INT(argv[0]), NUM2INT(argv[1]),
                       NUM2INT(argv[2]), NUM2INT(argv[3]));
    return self;
}

draw_rect(x, y, w, h, r, g, b, a 255)

Draw a rectangle outline.

Parameters

x Integer — left edge
y Integer — top edge
w Integer — width
h Integer — height
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

static VALUE
renderer_draw_rect(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    SDL_Rect rect;
    Uint8 r, g, b, a = 255;

    rb_check_arity(argc, 7, 8);
    rect.x = NUM2INT(argv[0]);
    rect.y = NUM2INT(argv[1]);
    rect.w = NUM2INT(argv[2]);
    rect.h = NUM2INT(argv[3]);
    r = (Uint8)NUM2INT(argv[4]);
    g = (Uint8)NUM2INT(argv[5]);
    b = (Uint8)NUM2INT(argv[6]);
    if (argc > 7) a = (Uint8)NUM2INT(argv[7]);

    SDL_SetRenderDrawBlendMode(ren->renderer, a < 255 ? SDL_BLENDMODE_BLEND : SDL_BLENDMODE_NONE);
    SDL_SetRenderDrawColor(ren->renderer, r, g, b, a);
    SDL_RenderDrawRect(ren->renderer, &rect);
    return self;
}

draw_text(x, y, text, font:, r: 255, g: 255, b: 255, a: 255)

Render text and blit it at the given position in a single call.

Creates a temporary texture, copies it to the renderer, then destroys it. For repeated rendering of the same text, prefer calling Font#render_text once and reusing the texture.

Parameters

x Integer — left edge
y Integer — top edge
text String — the text to render (UTF-8)
font Font — the font to use
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

Example

renderer.draw_text(10, 10, "Hello!", font: font, r: 255, g: 255, b: 255)

View source ▼

def draw_text(x, y, text, font:, r: 255, g: 255, b: 255, a: 255)
  tex = font.render_text(text, r, g, b, a)
  copy(tex, nil, [x, y, tex.width, tex.height])
  tex.destroy
  self
end

fill(x, y, w, h, r:, g:, b:, a: 255)

Draw a filled rectangle (keyword-arg wrapper for #fill_rect).

Parameters

x Integer — left edge
y Integer — top edge
w Integer — width
h Integer — height
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

def fill(x, y, w, h, r:, g:, b:, a: 255)
  fill_rect(x, y, w, h, r, g, b, a)
end

fill_rect(x, y, w, h, r, g, b, a 255)

Draw a filled rectangle.

Parameters

x Integer — left edge
y Integer — top edge
w Integer — width
h Integer — height
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

static VALUE
renderer_fill_rect(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    SDL_Rect rect;
    Uint8 r, g, b, a = 255;

    rb_check_arity(argc, 7, 8);
    rect.x = NUM2INT(argv[0]);
    rect.y = NUM2INT(argv[1]);
    rect.w = NUM2INT(argv[2]);
    rect.h = NUM2INT(argv[3]);
    r = (Uint8)NUM2INT(argv[4]);
    g = (Uint8)NUM2INT(argv[5]);
    b = (Uint8)NUM2INT(argv[6]);
    if (argc > 7) a = (Uint8)NUM2INT(argv[7]);

    SDL_SetRenderDrawBlendMode(ren->renderer, a < 255 ? SDL_BLENDMODE_BLEND : SDL_BLENDMODE_NONE);
    SDL_SetRenderDrawColor(ren->renderer, r, g, b, a);
    SDL_RenderFillRect(ren->renderer, &rect);
    return self;
}

line(x1, y1, x2, y2, r:, g:, b:, a: 255)

Draw a line (keyword-arg wrapper for #draw_line).

Parameters

x1 Integer — start x
y1 Integer — start y
x2 Integer — end x
y2 Integer — end y
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

def line(x1, y1, x2, y2, r:, g:, b:, a: 255)
  draw_line(x1, y1, x2, y2, r, g, b, a)
end

load_font(path, size)

Load a TrueType font file at the given point size.

Parameters

path String — path to a .ttf or .otf font file
size Integer — point size

Returns Font

Example

font = renderer.load_font("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 16)

View source ▼

def load_font(path, size)
  Font.new(self, path, size)
end

load_image(path)

Load an image file into a GPU texture via SDL2_image. Supports PNG, JPG, BMP, GIF, WebP, TGA, and more. Alpha blending is enabled automatically.

Parameters

path String — path to the image file

Returns Texture

Example

sprite = renderer.load_image("assets/player.png")
renderer.copy(sprite, nil, [x, y, sprite.width, sprite.height])

View source ▼

static VALUE
renderer_load_image(VALUE self, VALUE path)
{
    struct sdl2_renderer *ren = get_renderer(self);

    ensure_sdl2_init();
    ensure_img_init();

    StringValue(path);
    const char *cpath = StringValueCStr(path);

    SDL_Texture *texture = IMG_LoadTexture(ren->renderer, cpath);
    if (!texture) {
        rb_raise(rb_eRuntimeError, "IMG_LoadTexture failed: %s", IMG_GetError());
    }

    /* Query dimensions */
    int w, h;
    SDL_QueryTexture(texture, NULL, NULL, &w, &h);

    /* Enable alpha blending (common for PNGs with transparency) */
    SDL_SetTextureBlendMode(texture, SDL_BLENDMODE_BLEND);

    /* Wrap as a Texture object */
    VALUE klass = rb_const_get(mTeekSDL2, rb_intern("Texture"));
    VALUE obj = rb_obj_alloc(klass);

    struct sdl2_texture *t;
    TypedData_Get_Struct(obj, struct sdl2_texture, &texture_type, t);
    t->texture = texture;
    t->w = w;
    t->h = h;
    t->renderer_obj = self;

    return obj;
}

outline(x, y, w, h, r:, g:, b:, a: 255)

Draw a rectangle outline (keyword-arg wrapper for #draw_rect).

Parameters

x Integer — left edge
y Integer — top edge
w Integer — width
h Integer — height
r Integer — red (0–255)
g Integer — green (0–255)
b Integer — blue (0–255)
a Integer — alpha (0–255)

Returns self

View source ▼

def outline(x, y, w, h, r:, g:, b:, a: 255)
  draw_rect(x, y, w, h, r, g, b, a)
end

output_size

Query the renderer’s output dimensions.

Returns Array(Integer, Integer) — [width, height]

View source ▼

static VALUE
renderer_output_size(VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    int w, h;

    if (SDL_GetRendererOutputSize(ren->renderer, &w, &h) != 0) {
        rb_raise(eSDL2Error, "SDL_GetRendererOutputSize: %s", SDL_GetError());
    }
    return rb_ary_new_from_args(2, INT2NUM(w), INT2NUM(h));
}

present

Present the back buffer to the screen. Called automatically by #render.

Returns self

View source ▼

static VALUE
renderer_present(VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    SDL_RenderPresent(ren->renderer);
    return self;
}

read_pixels

Read the current renderer contents as raw RGBA pixel data.

Returns String — binary string of width*height*4 bytes (RGBA8888)

View source ▼

static VALUE
renderer_read_pixels(VALUE self)
{
    struct sdl2_renderer *ren = get_renderer(self);
    int w, h;

    if (SDL_GetRendererOutputSize(ren->renderer, &w, &h) != 0) {
        rb_raise(eSDL2Error, "SDL_GetRendererOutputSize: %s", SDL_GetError());
    }

    long size = (long)w * h * 4;
    VALUE buf = rb_str_buf_new(size);
    rb_str_set_len(buf, size);

    if (SDL_RenderReadPixels(ren->renderer, NULL, SDL_PIXELFORMAT_RGBA8888,
                             RSTRING_PTR(buf), w * 4) != 0) {
        rb_raise(eSDL2Error, "SDL_RenderReadPixels: %s", SDL_GetError());
    }

    return buf;
}

render

Yield self for a drawing block, then present.

Returns self

@yield renderer draw commands

@yieldparam renderer Renderer

Example

renderer.render do |r|
  r.clear(0, 0, 0)
  r.fill(10, 10, 100, 100, r: 255, g: 0, b: 0)
end

View source ▼

def render
  yield self
  present
  self
end

save_png(path)

Save the current renderer contents to a PNG file via ImageMagick.

Reads raw pixels from the GPU and pipes them through ImageMagick’s convert command to produce a PNG. Useful for visual inspection and screenshot-based regression testing.

Parameters

path String — output file path (should end in .png)

Returns void

@raise RuntimeError if ImageMagick is not installed or conversion fails

Example

renderer.clear(0, 0, 0)
renderer.fill_rect(10, 10, 100, 50, 255, 0, 0)
renderer.save_png("screenshot.png")

View source ▼

def save_png(path)
  w, h = output_size
  pixels = read_pixels

  cmd = ["magick", "-size", "#{w}x#{h}", "-depth", "8", "rgba:-", path]
  IO.popen(cmd, "wb") do |io|
    io.write(pixels)
  end

  unless $?.success?
    raise "save_png failed: is ImageMagick installed? (brew install imagemagick / apt-get install imagemagick)"
  end
end

Teek API Documentation

Teek::SDL2::Renderer Class

C-defined methods

Instance Methods ↑

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example