Class: SDL2::Surface

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

Overview

This class represents bitmap images (collection of pixels).

Normally in SDL2, this class is not used for drawing a image on a window. Texture is used for the purpose.

Mainly this class is for compatibility with SDL1, but the class is useful for simple pixel manipulation. For example, TTF can create only surfaces, not textures. You can convert a surface to texture with Renderer#create_texture_from.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (nil) blit(src, srcrect, dst, dstrect)

Perform a fast blit from src surface to dst surface.

Parameters:

  • src (SDL2::Surface) —

    the source surface

  • srcrect (SDL2::Rect, nil) —

    the region in the source surface, if nil is given, the whole source is used

  • dst (SDL2::Surface) —

    the destination surface

  • dstrect (SDL2::Rect, nil) —

    the region in the destination surface if nil is given, the source image is copied to (0, 0) on the destination surface. dstrect is changed by this method to store the actually copied region (since the surface has clipping functionality, actually copied region may be different from given dstrect).

Returns:

  • (nil) 


2235
2236
2237
2238
2239
2240
2241
2242
 
# File 'video.c', line 2235

static VALUE Surface_s_blit(VALUE self, VALUE src, VALUE srcrect, VALUE dst, VALUE dstrect)
{
    HANDLE_ERROR(SDL_BlitSurface(Get_SDL_Surface(src),
                                 Get_SDL_Rect_or_NULL(srcrect),
                                 Get_SDL_Surface(dst),
                                 Get_SDL_Rect_or_NULL(dstrect)));
    return Qnil;
}

+ (SDL2::Surface) from_string(string, width, heigth, depth, pitch = nil, rmask = nil, gmask = nil, bmask = nil, amask = nil)

Create a RGB surface from pixel data as String object.

If rmask, gmask, bmask are omitted, the default masks are used. If amask is omitted, alpha mask is considered to be zero.

Parameters:

  • string (String) —

    the pixel data

  • width (Integer) —

    the width of the creating surface

  • height (Integer) —

    the height of the creating surface

  • depth (Integer) —

    the color depth (in bits) of the creating surface

  • pitch (Integer) (defaults to: nil) —

    the number of bytes of one scanline if this argument is omitted, width*depth/8 is used.

  • rmask (Integer) (defaults to: nil) —

    the red mask of a pixel

  • gmask (Integer) (defaults to: nil) —

    the green mask of a pixel

  • bmask (Integer) (defaults to: nil) —

    the blue mask of a pixel

  • amask (Integer) (defaults to: nil) —

    the alpha mask of a pixel

Returns:

Raises:

  • (SDL2::Error) —

    raised when an error occurs in C SDL library



1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
 
# File 'video.c', line 1903

static VALUE Surface_s_from_string(int argc, VALUE* argv, VALUE self)
{
    VALUE string, width, height, depth, pitch, Rmask, Gmask, Bmask, Amask;
    int w, h, d, p, r, g, b, a;
    SDL_Surface* surface;
    void* pixels;
    Surface* s;
    
    rb_scan_args(argc, argv, "45", &string, &width, &height, &depth,
                 &pitch, &Rmask, &Gmask, &Bmask, &Amask);
    StringValue(string);
    w = NUM2INT(width);
    h = NUM2INT(height);
    d = NUM2INT(depth);
    p = (pitch == Qnil) ? d*w/8 : NUM2INT(pitch);
    r = (Rmask == Qnil) ? 0 : NUM2UINT(Rmask);
    g = (Gmask == Qnil) ? 0 : NUM2UINT(Gmask);
    b = (Bmask == Qnil) ? 0 : NUM2UINT(Bmask);
    a = (Amask == Qnil) ? 0 : NUM2UINT(Amask);

    if (RSTRING_LEN(string) < p*h)
        rb_raise(rb_eArgError, "String too short");
    if (p < d*w/8 )
        rb_raise(rb_eArgError, "pitch too small");

    pixels = ruby_xmalloc(RSTRING_LEN(string));
    memcpy(pixels, RSTRING_PTR(string), RSTRING_LEN(string));
    surface = SDL_CreateRGBSurfaceFrom(pixels, w, h, d, p, r, g, b, a);
    if (!surface)
        SDL_ERROR();
    
    RB_GC_GUARD(string);

    s = ALLOC(Surface);
    s->surface = surface;
    s->need_to_free_pixels = 1;
    return Data_Wrap_Struct(cSurface, 0, Surface_free, s);
}

+ (SDL2::Surface) load(file)

Load file and create a new SDL2::Surface.

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



3209
3210
3211
3212
3213
3214
3215
3216
3217
 
# File 'video.c', line 3209

static VALUE Surface_s_load(VALUE self, VALUE fname)
{
    SDL_Surface* surface = IMG_Load(StringValueCStr(fname));
    if (!surface) {
        SDL_SetError(IMG_GetError());
        SDL_ERROR();
    }
    return Surface_new(surface);
}

+ (SDL2::Surface) load_bmp(path)

Load a surface from bmp file.

Parameters:

  • path (String) —

    bmp file path

Returns:

Raises:

  • (SDL2::Error) —

    raised when an error occurs. For example, if there is no file or the file file format is not Windows BMP.



1871
1872
1873
1874
1875
1876
1877
1878
1879
 
# File 'video.c', line 1871

static VALUE Surface_s_load_bmp(VALUE self, VALUE fname)
{
    SDL_Surface* surface = SDL_LoadBMP(StringValueCStr(fname));

    if (surface == NULL)
        HANDLE_ERROR(-1);

    return Surface_new(surface);
}

+ (SDL2::Surface) new(width, height, depth) + (SDL2::Surface) new(width, height, depth, amask) + (SDL2::Surface) new(width, heigth, depth, rmask, gmask, bmask, amask)

Create an empty RGB surface.

If rmask, gmask, bmask are omitted, the default masks are used. If amask is omitted, alpha mask is considered to be zero.

Parameters:

  • width (Integer) —

    the width of the new surface

  • height (Integer) —

    the height of the new surface

  • depth (Integer) —

    the bit depth of the new surface

  • rmask (Integer) —

    the red mask of a pixel

  • gmask (Integer) —

    the green mask of a pixel

  • bmask (Integer) —

    the blue mask of a pixel

  • amask (Integer) —

    the alpha mask of a pixel

Returns:



2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
 
# File 'video.c', line 2264

static VALUE Surface_s_new(int argc, VALUE* argv, VALUE self)
{
    VALUE width, height, depth;
    Uint32 Rmask, Gmask, Bmask, Amask;
    SDL_Surface * surface;
    
    if  (argc == 3) {
        rb_scan_args(argc, argv, "30", &width, &height, &depth);
        Rmask = Gmask = Bmask = Amask = 0;
    } else if (argc == 7) {
        VALUE rm, gm, bm, am;
        rb_scan_args(argc, argv, "70", &width, &height, &depth, &rm, &gm, &bm, &am);
        Rmask = NUM2UINT(rm); Gmask = NUM2UINT(gm); 
        Bmask = NUM2UINT(bm); Amask = NUM2UINT(am);
    } else {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 4 or 7)", argc);
    }

    surface = SDL_CreateRGBSurface(0, NUM2INT(width), NUM2INT(height), NUM2INT(depth),
                                   Rmask, Gmask, Bmask, Amask);
    if (!surface)
        SDL_ERROR();

    return Surface_new(surface);
}

Instance Method Details

- (Integer) bits_per_pixel

Get bits per pixel of the surface.

Returns:

  • (Integer) 


2084
2085
2086
2087
 
# File 'video.c', line 2084

static VALUE Surface_bits_per_pixel(VALUE self)
{
    return UCHAR2NUM(Get_SDL_Surface(self)->format->BitsPerPixel);
}

- (Integer) blend_mode

Get the blending mode of the surface used for blit operations.

Returns:

  • (Integer)

See Also:



1966
1967
1968
1969
1970
1971
 
# File 'video.c', line 1966

static VALUE Surface_blend_mode(VALUE self)
{
    SDL_BlendMode mode;
    HANDLE_ERROR(SDL_GetSurfaceBlendMode(Get_SDL_Surface(self), &mode));
    return INT2FIX(mode);
}

- (mode) blend_mode=(mode)

Set the blending mode of the surface used for blit operations.

Parameters:

  • mode (Integer) —

    the blending mode

Returns:

  • (mode)

See Also:



1981
1982
1983
1984
1985
 
# File 'video.c', line 1981

static VALUE Surface_set_blend_mode(VALUE self, VALUE mode)
{
    HANDLE_ERROR(SDL_SetSurfaceBlendMode(Get_SDL_Surface(self), NUM2INT(mode)));
    return mode;
}

- (Integer) bytes_per_pixel

Get bytes per pixel of the surface.

Returns:

  • (Integer) 


2094
2095
2096
2097
 
# File 'video.c', line 2094

static VALUE Surface_bytes_per_pixel(VALUE self)
{
    return UCHAR2NUM(Get_SDL_Surface(self)->format->BytesPerPixel);
}

- (Integer) color_key

Get the color key of the surface

Returns:

  • (Integer) —

    the color key, as pixel value (see #pixel)

See Also:



2189
2190
2191
2192
2193
2194
2195
2196
 
# File 'video.c', line 2189

static VALUE Surface_color_key(VALUE self)
{
    Uint32 key;
    if (SDL_GetColorKey(Get_SDL_Surface(self), &key) < 0)
        return Qnil;
    else
        return UINT2NUM(key);
}

- (key) color_key=(key)

Set the color key of the surface

Parameters:

  • key (Integer, Array<Integer>) —

    the color key, pixel value (see #pixel) or pixel color (array of three or four integer elements).

Returns:

  • (key)

See Also:



2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
 
# File 'video.c', line 2170

static VALUE Surface_set_color_key(VALUE self, VALUE key)
{
    SDL_Surface* surface = Get_SDL_Surface(self);
    if (key == Qnil)
        return Surface_unset_color_key(self);
    
    HANDLE_ERROR(SDL_SetColorKey(surface, SDL_TRUE, pixel_value(key, surface->format)));
    
    return key;
}

- (nil) destroy

Destroy the surface and deallocate the memory for pixels.

Returns:

  • (nil)

See Also:



1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
 
# File 'video.c', line 1948

static VALUE Surface_destroy(VALUE self)
{
    Surface* s = Get_Surface(self);
    if (s->need_to_free_pixels)
        free(s->surface->pixels);
    s->need_to_free_pixels = 0;
    if (s->surface)
        SDL_FreeSurface(s->surface);
    s->surface = NULL;
    return Qnil;
}

- (Boolean) destroy?

Return true if the surface is destroyed.

Returns:

  • (Boolean)

- (Integer) h

Get the height of the surface.

Returns:

  • (Integer) 


2213
2214
2215
2216
 
# File 'video.c', line 2213

static VALUE Surface_h(VALUE self)
{
    return INT2NUM(Get_SDL_Surface(self)->h);
}

- (nil) lock

Lock the surface.

Returns:

  • (nil)

See Also:



2006
2007
2008
2009
2010
 
# File 'video.c', line 2006

static VALUE Surface_lock(VALUE self)
{
    HANDLE_ERROR(SDL_LockSurface(Get_SDL_Surface(self)));
    return Qnil;
}

- (Boolean) must_lock?

Return true if the surface need to lock when you get access to the pixel data of the surface.

Returns:

  • (Boolean)

See Also:



1993
1994
1995
1996
 
# File 'video.c', line 1993

static VALUE Surface_must_lock_p(VALUE self)
{
    return INT2BOOL(SDL_MUSTLOCK(Get_SDL_Surface(self)));
}

- (Integer) pitch

Get the pitch (bytes per horizontal line) of the surface.

Returns:

  • (Integer) 


2074
2075
2076
2077
 
# File 'video.c', line 2074

static VALUE Surface_pitch(VALUE self)
{
    return UINT2NUM(Get_SDL_Surface(self)->pitch);
}

- (Integer) pixel(x, y)

Get a pixel data at (x, y)

Parameters:

  • x (Integer) —

    the x coordinate

  • y (Integer) —

    the y coordinate

Returns:

  • (Integer) —

    pixel data

See Also:



2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
 
# File 'video.c', line 2036

static VALUE Surface_pixel(VALUE self, VALUE x_coord, VALUE y_coord)
{
    int x = NUM2INT(x_coord);
    int y = NUM2INT(y_coord);
    SDL_Surface* surface = Get_SDL_Surface(self);
    int offset;
    Uint32 pixel = 0;
    int i;
    
    if (x < 0 || x >= surface->w || y < 0 || y >= surface->h)
        rb_raise(rb_eArgError, "(%d, %d) out of range for %dx%d",
                 x, y, surface->w, surface->h);
    offset = surface->pitch * y + surface->format->BytesPerPixel * x;
    for (i=0; i<surface->format->BytesPerPixel; ++i) {
        pixel += *((Uint8*)surface->pixels + offset + i) << (8*i);
    }

    return UINT2NUM(SDL_SwapLE32(pixel));
}

- ([Integer, Integer, Integer, Integer]) pixel_color(x, y)

Get the pixel color (r,g,b and a) at (x, y) of the surface.

Parameters:

  • x (Integer) —

    the x coordinate

  • y (Integer) —

    the y coordinate

Returns:

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

    the red, green, blue, and alpha component of the specified pixel.



2109
2110
2111
2112
2113
2114
2115
2116
2117
 
# File 'video.c', line 2109

static VALUE Surface_pixel_color(VALUE self, VALUE x, VALUE y)
{
    Uint32 pixel = NUM2UINT(Surface_pixel(self, x, y));
    SDL_Surface* surface = Get_SDL_Surface(self);
    Uint8 r, g, b, a;
    SDL_GetRGBA(pixel, surface->format, &r, &g, &b, &a);

    return rb_ary_new3(4, UCHAR2NUM(r), UCHAR2NUM(g), UCHAR2NUM(b), UCHAR2NUM(a));
}

- (String) pixels

Get all pixel data of the surface as a string.

Returns:

  • (String) 


2062
2063
2064
2065
2066
2067
 
# File 'video.c', line 2062

static VALUE Surface_pixels(VALUE self)
{
    SDL_Surface* surface = Get_SDL_Surface(self);
    int size = surface->h * surface->pitch;
    return rb_str_new(surface->pixels, size);
}

- (nil) unlock

Unlock the surface.

Returns:

  • (nil)

See Also:



2019
2020
2021
2022
2023
 
# File 'video.c', line 2019

static VALUE Surface_unlock(VALUE self)
{
    SDL_UnlockSurface(Get_SDL_Surface(self));
    return Qnil;
}

- (key) color_key=(key)

Set the color key of the surface

Parameters:

  • key (Integer, Array<Integer>) —

    the color key, pixel value (see #pixel) or pixel color (array of three or four integer elements).

Returns:

  • (key)

See Also:



2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
 
# File 'video.c', line 2170

static VALUE Surface_set_color_key(VALUE self, VALUE key)
{
    SDL_Surface* surface = Get_SDL_Surface(self);
    if (key == Qnil)
        return Surface_unset_color_key(self);
    
    HANDLE_ERROR(SDL_SetColorKey(surface, SDL_TRUE, pixel_value(key, surface->format)));
    
    return key;
}

- (Integer) w

Get the width of the surface.

Returns:

  • (Integer) 


2203
2204
2205
2206
 
# File 'video.c', line 2203

static VALUE Surface_w(VALUE self)
{
    return INT2NUM(Get_SDL_Surface(self)->w);
}