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

FLIP_NONE =

Do not flip, used in #copy_ex

INT2FIX(SDL_FLIP_NONE)
FLIP_HORIZONTAL =

Flip horizontally, used in #copy_ex

INT2FIX(SDL_FLIP_HORIZONTAL)
FLIP_VERTICAL =

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:



1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
 
# File 'video.c', line 1177

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:



1343
1344
1345
1346
1347
 
# File 'video.c', line 1343

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) 


1544
1545
1546
1547
 
# File 'video.c', line 1544

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:



1517
1518
1519
1520
1521
1522
 
# File 'video.c', line 1517

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) ⇒ rect

Set the clip rectangle for the current target.

Returns:

  • (rect)

See Also:



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

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:



1278
1279
1280
1281
1282
1283
1284
1285
 
# File 'video.c', line 1278

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:



1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
 
# File 'video.c', line 1314

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:



1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
 
# File 'video.c', line 1223

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:



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

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



1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
 
# File 'video.c', line 1718

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:



1196
1197
1198
1199
1200
 
# File 'video.c', line 1196

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:



1480
1481
1482
1483
1484
1485
 
# File 'video.c', line 1480

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:



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

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 ⇒ [Integer,Integer,Integer,Integer]

Get the color used for drawing operations

Returns:

  • ([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:



1357
1358
1359
1360
1361
1362
 
# File 'video.c', line 1357

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) ⇒ color

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 ([Integer, Integer, Integer]) —

    red, green, and blue components used for drawing

  • color ([Integer, Integer, Integer, Integer]) —

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

Returns:

  • (color)

See Also:



1388
1389
1390
1391
1392
1393
1394
1395
1396
 
# File 'video.c', line 1388

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) 


1409
1410
1411
1412
1413
1414
 
# File 'video.c', line 1409

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) 


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

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) 


1439
1440
1441
1442
1443
 
# File 'video.c', line 1439

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) 


1453
1454
1455
1456
1457
 
# File 'video.c', line 1453

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:



1464
1465
1466
1467
1468
1469
 
# File 'video.c', line 1464

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:



3492
3493
3494
3495
3496
3497
3498
3499
3500
 
# File 'video.c', line 3492

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 ⇒ [Integer, Integer]

Get device indepndent resolution for rendering.

Returns:

  • ([Integer, Integer]) —

    the logical width and height

See Also:



1556
1557
1558
1559
1560
1561
 
# File 'video.c', line 1556

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) ⇒ w_and_h

Set a device indepndent resolution for rendering.

Parameters:

  • w_and_h ([Integer, Integer]) —

    the width and height of the logical resolution

Returns:

  • (w_and_h)

See Also:



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

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 ⇒ [Integer, Integer]

Get the output size of a rendering context.

Returns:

  • ([Integer, Integer]) —

    the width and the height



1660
1661
1662
1663
1664
1665
 
# File 'video.c', line 1660

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) 


1331
1332
1333
1334
1335
 
# File 'video.c', line 1331

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

#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:



1702
1703
1704
1705
 
# File 'video.c', line 1702

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

#render_target=(target) ⇒ target

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)

Returns:

  • (target)

See Also:



1685
1686
1687
1688
1689
1690
1691
 
# File 'video.c', line 1685

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) 


1712
1713
1714
1715
 
# File 'video.c', line 1712

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

#scale ⇒ [Integer, Integer]

Get the drawing scale for the current target.

Returns:

  • ([Integer, Integer]) —

    horizontal and vertical scale factor

See Also:



1586
1587
1588
1589
1590
1591
 
# File 'video.c', line 1586

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) ⇒ scaleX_and_scaleY

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 ([Float, Float]) —

    the horizontal and vertical scaling factors

Returns:

  • (scaleX_and_scaleY)

See Also:



1609
1610
1611
1612
1613
1614
1615
1616
 
# File 'video.c', line 1609

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:



1650
1651
1652
1653
 
# File 'video.c', line 1650

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:



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

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) ⇒ area

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

Returns:

  • (area)

See Also:



1639
1640
1641
1642
1643
 
# File 'video.c', line 1639

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