Class: SDL2::Renderer

Inherits:
Object
  • Object
show all
Defined in:
video.c,
video.c

Overview

This class represents a 2D rendering context for a window.

You can create a renderer using Window#create_renderer and use it to draw figures on the window.

Defined Under Namespace

Modules: Flags Classes: Info

Constant Summary collapse

FLIP_NONE =

Returns Do not flip, used in #copy_ex.

Returns:

  • (Integer) —

    Do not flip, used in #copy_ex

INT2FIX(SDL_FLIP_NONE)
FLIP_HORIZONTAL =

Returns Flip horizontally, used in #copy_ex.

Returns:

  • (Integer) —

    Flip horizontally, used in #copy_ex

INT2FIX(SDL_FLIP_HORIZONTAL)
FLIP_VERTICAL =

Returns Flip vertically, used in #copy_ex.

Returns:

  • (Integer) —

    Flip vertically, used in #copy_ex

INT2FIX(SDL_FLIP_VERTICAL)

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.drivers_info ⇒ Array<SDL2::Renderer::Info>

Return information of all available rendering contexts.

Returns:



1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
 
# File 'video.c', line 1198

static VALUE Renderer_s_drivers_info(VALUE self)
{
    int num_drivers = SDL_GetNumRenderDrivers();
    VALUE info_ary = rb_ary_new();
    int i;
    for (i=0; i<num_drivers; ++i) {
        SDL_RendererInfo info;
        HANDLE_ERROR(SDL_GetRenderDriverInfo(i, &info));
        rb_ary_push(info_ary, RendererInfo_new(&info));
    }
    return info_ary;
}

Instance Method Details

#clear ⇒ nil

Crear the rendering target with the drawing color.

Returns:

  • (nil)

See Also:



1412
1413
1414
1415
1416
 
# File 'video.c', line 1412

static VALUE Renderer_clear(VALUE self)
{
    HANDLE_ERROR(SDL_RenderClear(Get_SDL_Renderer(self)));
    return Qnil;
}

#clip_enabled? ⇒ Boolean

Note:

This method is available since SDL 2.0.4.

Get whether clipping is enabled on the renderer.

Returns:

  • (Boolean) 


1612
1613
1614
1615
 
# File 'video.c', line 1612

static VALUE Render_clip_enabled_p(VALUE self)
{
    return INT2BOOL(SDL_RenderIsClipEnabled(Get_SDL_Renderer(self)));
}

#clip_rect ⇒ SDL2::Rect

Get the clip rectangle for the current target.

Returns:

See Also:



1584
1585
1586
1587
1588
1589
 
# File 'video.c', line 1584

static VALUE Renderer_clip_rect(VALUE self)
{
    VALUE rect = rb_obj_alloc(cRect);
    SDL_RenderGetClipRect(Get_SDL_Renderer(self), Get_SDL_Rect(rect));
    return rect;
}

#clip_rect=(rect) ⇒ void

This method returns an undefined value.

Set the clip rectangle for the current target.

Parameters:

See Also:



1600
1601
1602
1603
1604
 
# File 'video.c', line 1600

static VALUE Renderer_set_clip_rect(VALUE self, VALUE rect)
{
    HANDLE_ERROR(SDL_RenderSetClipRect(Get_SDL_Renderer(self), Get_SDL_Rect(rect)));
    return rect;
}

#copy(texture, srcrect, dstrect) ⇒ void

This method returns an undefined value.

Copy a portion of the texture to the current rendering target.

Parameters:

  • texture (SDL2::Texture) —

    the source texture

  • srcrect (SDL2::Rect, nil) —

    the source rectangle, or nil for the entire texture

  • dstrect (SDL2::Rect, nil) —

    the destination rectangle, or nil for the entire rendering target; the texture will be stretched to fill the given rectangle

See Also:



1299
1300
1301
1302
1303
1304
1305
1306
 
# File 'video.c', line 1299

static VALUE Renderer_copy(VALUE self, VALUE texture, VALUE srcrect, VALUE dstrect)
{
    HANDLE_ERROR(SDL_RenderCopy(Get_SDL_Renderer(self),
                                Get_SDL_Texture(texture),
                                Get_SDL_Rect_or_NULL(srcrect),
                                Get_SDL_Rect_or_NULL(dstrect)));
    return Qnil;
}

#copy_ex(texture, srcrect, dstrect, angle, center, flip) ⇒ void

This method returns an undefined value.

Copy a portion of the texture to the current rendering target, rotating it by angle around the given center and also flipping it top-bottom and/or left-right.

You can use the following constants to specify the horizontal/vertical flip:

Parameters:

  • texture (SDL2::Texture) —

    the source texture

  • srcrect (SDL2::Rect, nil) —

    the source rectangle, or nil for the entire texture

  • dstrect (SDL2::Rect, nil) —

    the destination rectangle, or nil for the entire rendering target; the texture will be stretched to fill the given rectangle

  • angle (Float) —

    an angle in degree indicating the rotation that will be applied to dstrect

  • center (SDL2::Point, nil) —

    the point around which dstrect will be rotated, (if nil, rotation will be done around the center of dstrect)

  • flip (Integer) —

    bits OR’d of the flip consntants

See Also:



1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
 
# File 'video.c', line 1335

static VALUE Renderer_copy_ex(VALUE self, VALUE texture, VALUE srcrect, VALUE dstrect,
                              VALUE angle, VALUE center, VALUE flip)
{
    HANDLE_ERROR(SDL_RenderCopyEx(Get_SDL_Renderer(self),
                                  Get_SDL_Texture(texture),
                                  Get_SDL_Rect_or_NULL(srcrect),
                                  Get_SDL_Rect_or_NULL(dstrect),
                                  NUM2DBL(angle),
                                  Get_SDL_Point_or_NULL(center),
                                  NUM2INT(flip)));
    return Qnil;
}

#create_texture(format, access, w, h) ⇒ SDL2::Texture

Create a new texture for the rendering context.

You can use the following constants to specify access pattern

Parameters:

  • format (SDL2::PixelFormat, Integer) —

    format of the texture

  • access (Integer) —

    texture access pattern

  • w (Integer) —

    the width ofthe texture in pixels

  • h (Integer) —

    the height ofthe texture in pixels

Returns:

Raises:

  • (SDL2::Error) —

    raised when the texture cannot be created

See Also:



1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
 
# File 'video.c', line 1244

static VALUE Renderer_create_texture(VALUE self, VALUE format, VALUE access,
                                     VALUE w, VALUE h)
{
    SDL_Texture* texture = SDL_CreateTexture(Get_SDL_Renderer(self),
                                             uint32_for_format(format),
                                             NUM2INT(access), NUM2INT(w), NUM2INT(h));
    if (!texture)
        SDL_ERROR();
    return Texture_new(texture, Get_Renderer(self));
}

#create_texture_from(surface) ⇒ SDL2::Texture

Create a texture from an existing surface.

Parameters:

  • surface (SDL2::Surface) —

    the surface containing pixels for the texture

Returns:

Raises:

  • (SDL2::Error) —

    raised when the texture cannot be created

See Also:



1266
1267
1268
1269
1270
1271
1272
1273
1274
 
# File 'video.c', line 1266

static VALUE Renderer_create_texture_from(VALUE self, VALUE surface)
{
    SDL_Texture* texture = SDL_CreateTextureFromSurface(Get_SDL_Renderer(self),
                                                        Get_SDL_Surface(surface));
    if (texture == NULL)
        SDL_ERROR();

    return Texture_new(texture, Get_Renderer(self));
}

#debug_info ⇒ Hash<String=>Object>

Returns (GC) debug information.

Returns:

  • (Hash<String=>Object>) —

    (GC) debug information



1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
 
# File 'video.c', line 1786

static VALUE Renderer_debug_info(VALUE self)
{
    Renderer* r = Get_Renderer(self);
    VALUE info = rb_hash_new();
    int num_active_textures = 0;
    int i;
    rb_hash_aset(info, rb_str_new2("destroy?"), INT2BOOL(r->renderer == NULL));
    rb_hash_aset(info, rb_str_new2("max_textures"), INT2NUM(r->max_textures));
    rb_hash_aset(info, rb_str_new2("num_textures"), INT2NUM(r->num_textures));
    for (i=0; i<r->num_textures; ++i)
        if (r->textures[i]->texture)
            ++num_active_textures;
    rb_hash_aset(info, rb_str_new2("num_active_textures"), INT2NUM(num_active_textures));
    rb_hash_aset(info, rb_str_new2("refcount"), INT2NUM(r->refcount));

    return info;
}

#destroy ⇒ nil

Destroy the rendering context and free associated textures.

Returns:

  • (nil)

See Also:



1217
1218
1219
1220
1221
 
# File 'video.c', line 1217

static VALUE Renderer_destroy(VALUE self)
{
    Renderer_destroy_internal(Get_Renderer(self));
    return Qnil;
}

#destroy? ⇒ Boolean

Return true if the renderer is destroyed.

Returns:

  • (Boolean)

#draw_blend_mode ⇒ Integer

Get the blend mode used for drawing operations like #fill_rect and #draw_line.

Returns:

  • (Integer)

See Also:



1547
1548
1549
1550
1551
1552
 
# File 'video.c', line 1547

static VALUE Renderer_draw_blend_mode(VALUE self)
{
    SDL_BlendMode mode;
    HANDLE_ERROR(SDL_GetRenderDrawBlendMode(Get_SDL_Renderer(self), &mode));
    return INT2FIX(mode);
}

#draw_blend_mode=(mode) ⇒ Object

Set the blend mode used for drawing operations.

This method effects the following methods.

Parameters:

  • mode (Integer) —

    the blending mode

Returns:

  • mode

See Also:



1572
1573
1574
1575
1576
 
# File 'video.c', line 1572

static VALUE Renderer_set_draw_blend_mode(VALUE self, VALUE mode)
{
    HANDLE_ERROR(SDL_SetRenderDrawBlendMode(Get_SDL_Renderer(self), NUM2INT(mode)));
    return mode;
}

#draw_color ⇒ Array(Integer,Integer,Integer,Integer)

Get the color used for drawing operations

Returns:

  • (Array(Integer,Integer,Integer,Integer)) —

    red, green, blue, and alpha components of the drawing color (all components are more than or equal to 0 and less than and equal to 255)

See Also:



1426
1427
1428
1429
1430
1431
 
# File 'video.c', line 1426

static VALUE Renderer_draw_color(VALUE self)
{
    Uint8 r, g, b, a;
    HANDLE_ERROR(SDL_GetRenderDrawColor(Get_SDL_Renderer(self), &r, &g, &b, &a));
    return rb_ary_new3(4, INT2FIX(r), INT2FIX(g), INT2FIX(b), INT2FIX(a));
}

#draw_color=(color) ⇒ Array<Integer>

Set the color used for drawing operations

All color components (including alpha) must be more than or equal to 0 and less than and equal to 255

This method effects the following methods.

Parameters:

  • color (Array<Integer>) —

    red, green, blue, and optionally alpha components used for drawing

Returns:

  • (Array<Integer>)

See Also:



1455
1456
1457
1458
1459
1460
1461
1462
1463
 
# File 'video.c', line 1455

static VALUE Renderer_set_draw_color(VALUE self, VALUE rgba)
{
    SDL_Color color = Array_to_SDL_Color(rgba);

    HANDLE_ERROR(SDL_SetRenderDrawColor(Get_SDL_Renderer(self),
                                        color.r, color.g, color.b, color.a));

    return rgba;
}

#draw_line(x1, y1, x2, y2) ⇒ nil

Draw a line from (x1, y1) to (x2, y2) using drawing color given by #draw_color=.

Parameters:

  • x1 (Integer) —

    the x coordinate of the start point

  • y1 (Integer) —

    the y coordinate of the start point

  • x2 (Integer) —

    the x coordinate of the end point

  • y2 (Integer) —

    the y coordinate of the end point

Returns:

  • (nil) 


1476
1477
1478
1479
1480
1481
 
# File 'video.c', line 1476

static VALUE Renderer_draw_line(VALUE self, VALUE x1, VALUE y1, VALUE x2, VALUE y2)
{
    HANDLE_ERROR(SDL_RenderDrawLine(Get_SDL_Renderer(self),
                                    NUM2INT(x1), NUM2INT(y1), NUM2INT(x2), NUM2INT(y2)));
    return Qnil;
}

#draw_point(x, y) ⇒ nil

Draw a point at (x, y) using drawing color given by #draw_color=.

Parameters:

  • x (Integer) —

    the x coordinate of the point

  • y (Integer) —

    the y coordinate of the point

Returns:

  • (nil) 


1492
1493
1494
1495
1496
 
# File 'video.c', line 1492

static VALUE Renderer_draw_point(VALUE self, VALUE x, VALUE y)
{
    HANDLE_ERROR(SDL_RenderDrawPoint(Get_SDL_Renderer(self), NUM2INT(x), NUM2INT(y)));
    return Qnil;
}

#draw_rect(rect) ⇒ nil

Draw a rectangle using drawing color given by #draw_color=.

Parameters:

Returns:

  • (nil) 


1506
1507
1508
1509
1510
 
# File 'video.c', line 1506

static VALUE Renderer_draw_rect(VALUE self, VALUE rect)
{
    HANDLE_ERROR(SDL_RenderDrawRect(Get_SDL_Renderer(self), Get_SDL_Rect(rect)));
    return Qnil;
}

#fill_rect(rect) ⇒ nil

Draw a filled rectangle using drawing color given by #draw_color=.

Parameters:

Returns:

  • (nil) 


1520
1521
1522
1523
1524
 
# File 'video.c', line 1520

static VALUE Renderer_fill_rect(VALUE self, VALUE rect)
{
    HANDLE_ERROR(SDL_RenderFillRect(Get_SDL_Renderer(self), Get_SDL_Rect(rect)));
    return Qnil;
}

#info ⇒ SDL2::Renderer::Info

Get information about self rendering context .

Returns:



1531
1532
1533
1534
1535
1536
 
# File 'video.c', line 1531

static VALUE Renderer_info(VALUE self)
{
    SDL_RendererInfo info;
    HANDLE_ERROR(SDL_GetRendererInfo(Get_SDL_Renderer(self), &info));
    return RendererInfo_new(&info);
}

#load_texture(file) ⇒ SDL2::Texture

Load file and create a new Texture.

This method uses SDL_image. SDL_image supports following formats: BMP, CUR, GIF, ICO, JPG, LBP, PCX, PNG, PNM, TGA, TIF, XCF, XPM, and XV.

Parameters:

  • file (String) —

    the image file name to load a texture from

Returns:

Raises:

  • (SDL2::Error) —

    raised when you fail to load (for example, you have a wrong file name, or the file is broken)

See Also:



3614
3615
3616
3617
3618
3619
3620
3621
3622
 
# File 'video.c', line 3614

static VALUE Renderer_load_texture(VALUE self, VALUE fname)
{
    SDL_Texture* texture = IMG_LoadTexture(Get_SDL_Renderer(self), StringValueCStr(fname));
    if (!texture) {
        SDL_SetError("%s", IMG_GetError());
        SDL_ERROR();
    }
    return Texture_new(texture, Get_Renderer(self));
}

#logical_size ⇒ Array(Integer, Integer)

Get device indepndent resolution for rendering.

Returns:

  • (Array(Integer, Integer)) —

    the logical width and height

See Also:



1624
1625
1626
1627
1628
1629
 
# File 'video.c', line 1624

static VALUE Renderer_logical_size(VALUE self)
{
    int w, h;
    SDL_RenderGetLogicalSize(Get_SDL_Renderer(self), &w, &h);
    return rb_ary_new3(2, INT2FIX(w), INT2FIX(h));
}

#logical_size=(w_and_h) ⇒ void

This method returns an undefined value.

Set a device indepndent resolution for rendering.

Parameters:

  • w_and_h (Array(Integer, Integer)) —

    the width and height of the logical resolution

See Also:



1640
1641
1642
1643
1644
1645
1646
 
# File 'video.c', line 1640

static VALUE Renderer_set_logical_size(VALUE self, VALUE wh)
{
    HANDLE_ERROR(SDL_RenderSetLogicalSize(Get_SDL_Renderer(self),
                                          NUM2DBL(rb_ary_entry(wh, 0)),
                                          NUM2DBL(rb_ary_entry(wh, 1))));
    return wh;
}

#output_size ⇒ Array(Integer, Integer)

Get the output size of a rendering context.

Returns:

  • (Array(Integer, Integer)) —

    the width and the height



1728
1729
1730
1731
1732
1733
 
# File 'video.c', line 1728

static VALUE Renderer_output_size(VALUE self)
{
    int w, h;
    HANDLE_ERROR(SDL_GetRendererOutputSize(Get_SDL_Renderer(self), &w, &h));
    return rb_ary_new3(2, INT2FIX(w), INT2FIX(h));
}

#present ⇒ nil

Update the screen with rendering performed

Returns:

  • (nil) 


1352
1353
1354
1355
1356
 
# File 'video.c', line 1352

static VALUE Renderer_present(VALUE self)
{
    SDL_RenderPresent(Get_SDL_Renderer(self));
    return Qnil;
}

#read_pixels(rect, format) ⇒ String

Read pixels from the current rendering target.

Remarks

WARNING: This is a very slow operation, and should not be used frequently. If you’re using this on the main rendering target, it should be called after rendering and before #present.

Parameters:

  • rect (SDL2::Rect, nil) —

    the area to read, or nil for the entire target

  • format (SDL2::PixelFormat, Integer) —

    the desired pixel format (0 to use the format of the rendering target)

Returns:

  • (String) —

    raw pixel data as a binary string



1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
 
# File 'video.c', line 1373

static VALUE Renderer_read_pixels(VALUE self, VALUE rect, VALUE format)
{
    SDL_Renderer* renderer = Get_SDL_Renderer(self);
    SDL_Rect sdl_rect;
    SDL_Rect* rect_ptr = NULL;
    Uint32 fmt = uint32_for_format(format);
    int w, h, pitch;
    void* pixels;

    if (rect != Qnil) {
        sdl_rect = *Get_SDL_Rect(rect);
        rect_ptr = &sdl_rect;
        w = sdl_rect.w;
        h = sdl_rect.h;
    } else {
        HANDLE_ERROR(SDL_GetRendererOutputSize(renderer, &w, &h));
    }

    if (fmt == 0) {
        SDL_RendererInfo info;
        HANDLE_ERROR(SDL_GetRendererInfo(renderer, &info));
        pitch = w * SDL_BYTESPERPIXEL(info.texture_formats[0]);
    } else {
        pitch = w * SDL_BYTESPERPIXEL(fmt);
    }

    pixels = ALLOCA_N(char, pitch * h);

    HANDLE_ERROR(SDL_RenderReadPixels(renderer, rect_ptr, fmt, pixels, pitch));
    
    return rb_str_new(pixels, pitch * h);
}

#render_target ⇒ SDL2::Texture?

Get the current render target.

Returns:

  • (SDL2::Texture) —

    the current rendering target

  • (nil) —

    for the default render target (i.e. screen)

See Also:



1770
1771
1772
1773
 
# File 'video.c', line 1770

static VALUE Renderer_render_target(VALUE self)
{
    return rb_iv_get(self, "render_target");
}

#render_target=(target) ⇒ void

This method returns an undefined value.

Set a texture as the current render target.

Some renderers have ability to render to a texture instead of a screen. You can judge whether your renderer has this ability using #support_render_target?.

The target texture musbe be created with the Texture::ACCESS_TARGET flag.

Parameters:

  • target (SDL2::Texture, nil) —

    the targeted texture, or nil for the default render target(i.e. screen)

See Also:



1753
1754
1755
1756
1757
1758
1759
 
# File 'video.c', line 1753

static VALUE Renderer_set_render_target(VALUE self, VALUE target)
{
    HANDLE_ERROR(SDL_SetRenderTarget(Get_SDL_Renderer(self),
                                     (target == Qnil) ? NULL : Get_SDL_Texture(target)));
    rb_iv_set(self, "render_target", target);
    return target;
}

#reset_render_target ⇒ nil

Reset the render target to the screen.

Returns:

  • (nil) 


1780
1781
1782
1783
 
# File 'video.c', line 1780

static VALUE Renderer_reset_render_target(VALUE self)
{
    return Renderer_set_render_target(self, Qnil);
}

#scale ⇒ Array(Integer, Integer)

Get the drawing scale for the current target.

Returns:

  • (Array(Integer, Integer)) —

    horizontal and vertical scale factor

See Also:



1654
1655
1656
1657
1658
1659
 
# File 'video.c', line 1654

static VALUE Renderer_scale(VALUE self)
{
    float scaleX, scaleY;
    SDL_RenderGetScale(Get_SDL_Renderer(self), &scaleX, &scaleY);
    return rb_ary_new3(2, DBL2NUM(scaleX), DBL2NUM(scaleY));
}

#scale=(scaleX_and_scaleY) ⇒ void

This method returns an undefined value.

Set the drawing scale for rendering.

The drawing coordinates are scaled by the x/y scaling factors before they are used by the renderer. This allows resolution independent drawing with a single coordinate system.

If this results in scaling or subpixel drawing by the rendering backend, it will be handled using the appropriate quality hints. For best results use integer scaling factors.

Parameters:

  • scaleX_and_scaleY (Array(Float, Float)) —

    the horizontal and vertical scaling factors

See Also:



1677
1678
1679
1680
1681
1682
1683
1684
 
# File 'video.c', line 1677

static VALUE Renderer_set_scale(VALUE self, VALUE xy)
{
    float scaleX, scaleY;
    scaleX = NUM2DBL(rb_ary_entry(xy, 0));
    scaleY = NUM2DBL(rb_ary_entry(xy, 1));
    HANDLE_ERROR(SDL_RenderSetScale(Get_SDL_Renderer(self), scaleX, scaleY));
    return xy;
}

#support_render_target? ⇒ Boolean

Return true if the renderer supports render target.

Returns:

  • (Boolean)

See Also:



1718
1719
1720
1721
 
# File 'video.c', line 1718

static VALUE Renderer_support_render_target_p(VALUE self)
{
    return INT2BOOL(SDL_RenderTargetSupported(Get_SDL_Renderer(self)));
}

#viewport ⇒ SDL2::Rect

Get the drawing area for the current target.

Returns:

See Also:



1692
1693
1694
1695
1696
1697
 
# File 'video.c', line 1692

static VALUE Renderer_viewport(VALUE self)
{
    VALUE rect = rb_obj_alloc(cRect);
    SDL_RenderGetViewport(Get_SDL_Renderer(self), Get_SDL_Rect(rect));
    return rect;
}

#viewport=(area) ⇒ void

This method returns an undefined value.

Set the drawing area for rendering on the current target.

Parameters:

  • area (SDL2::Rect, nil) —

    the drawing area, or nil to set the viewport to the entire target

See Also:



1707
1708
1709
1710
1711
 
# File 'video.c', line 1707

static VALUE Renderer_set_viewport(VALUE self, VALUE rect)
{
    HANDLE_ERROR(SDL_RenderSetViewport(Get_SDL_Renderer(self), Get_SDL_Rect_or_NULL(rect)));
    return rect;
}