sfml3.rb

Class: SFML::Texture

Inherits:
Object
  • Object
show all
Defined in:
ext/graphics/texture.c,
ext/graphics/texture.c

Overview

An image living in GPU memory, usable for rendering (Sprite, Text, Shape) or as a render target (RenderTexture#texture).

#smooth?/#smooth=, #srgb?, and #repeated?/#repeated= control sampling; see each method for details.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(size) ⇒ Texture

Creates an empty texture with the given width and height.

Raises:

  • (RuntimeError) —

    if creation fails



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'ext/graphics/texture.c', line 105

static VALUE Texture_initialize(VALUE self, VALUE rb_size) {
    Texture* ptr;
    sfTexture* texture = sfTexture_create(vec2u_from_rb(rb_size));

    if (texture == NULL) {
        rb_raise(rb_eRuntimeError, "failed to create texture");
    }

    TypedData_Get_Struct(self, Texture, &Texture_data_type, ptr);
    ptr->texture = texture;
    ptr->owns = true;

    return self;
}

Class Method Details

.from_file(path) ⇒ Texture .from_file(path, area) ⇒ Texture

Loads a texture from the image file at filename.

Overloads:

Returns:

  • (Texture) —

    loaded from the file at path, cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if loading fails



142
143
144
145
146
147
148
149
150
 
# File 'ext/graphics/texture.c', line 142

static VALUE Texture_from_file(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_path, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_path, &rb_area);

    return Texture_wrap(klass, sfTexture_createFromFile(StringValueCStr(rb_path),
                                                        Texture_area_ptr(rb_area, &area)));
}

.from_image(image) ⇒ Texture .from_image(image, area) ⇒ Texture

Creates a texture from the pixels of an existing Image.

Overloads:

Returns:

  • (Texture) —

    built from image (an Image), cropped to area (a Rect) if given

Raises:

  • (TypeError) —

    if image is not an Image

  • (RuntimeError) —

    if creation fails



285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'ext/graphics/texture.c', line 285

static VALUE Texture_from_image(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_image, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_image, &rb_area);

    if (!rb_obj_is_kind_of(rb_image, Get_Klass_Image())) {
        raise_invalid_argument_class(Get_Klass_Image());
    }

    return Texture_wrap(klass, sfTexture_createFromImage(Get_Image_Struct(rb_image),
                                                         Texture_area_ptr(rb_area, &area)));
}

.from_memory(data) ⇒ Texture .from_memory(data, area) ⇒ Texture

Loads a texture from an in-memory image buffer.

Overloads:

Returns:

  • (Texture) —

    decoded from the encoded image bytes in data (a String), cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if decoding fails



182
183
184
185
186
187
188
189
190
191
192
 
# File 'ext/graphics/texture.c', line 182

static VALUE Texture_from_memory(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_data, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_data, &rb_area);
    StringValue(rb_data);

    return Texture_wrap(klass, sfTexture_createFromMemory(RSTRING_PTR(rb_data),
                                                          (size_t)RSTRING_LEN(rb_data),
                                                          Texture_area_ptr(rb_area, &area)));
}

.from_stream(stream) ⇒ Texture .from_stream(stream, area) ⇒ Texture

Loads a texture from the image data read from stream.

Overloads:

Returns:

  • (Texture) —

    decoded from stream (an InputStream), cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if decoding fails



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'ext/graphics/texture.c', line 226

static VALUE Texture_from_stream(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_stream, rb_area, holder = Qnil;
    sfIntRect area;
    sfInputStream* stream;

    if (argc < 1 || argc > 2) {
        raise_invalid_arguments_excepted(2, argc);
    }

    rb_stream = argv[0];
    rb_area = (argc == 2) ? argv[1] : Qnil;
    stream = input_stream_from_rb(rb_stream, &holder);

    (void)holder;

    return Texture_wrap(klass,
                        sfTexture_createFromStream(stream, Texture_area_ptr(rb_area, &area)));
}

.maximum_size ⇒ Integer

Returns the maximum texture size supported by the GPU.

Returns:

  • (Integer)

Returns:

  • (Integer) —

    the maximum texture size supported by the current OpenGL implementation



608
609
610
 
# File 'ext/graphics/texture.c', line 608

static VALUE Texture_maximum_size(VALUE klass) {
    return UINT2NUM(sfTexture_getMaximumSize());
}

.srgb(size) ⇒ Texture

Creates an empty texture with an sRGB format.

Returns:

Returns:

  • (Texture) —

    an empty sRGB-encoded texture of size

Raises:

  • (RuntimeError) —

    if creation fails



128
129
130
 
# File 'ext/graphics/texture.c', line 128

static VALUE Texture_srgb(VALUE klass, VALUE rb_size) {
    return Texture_wrap(klass, sfTexture_createSrgb(vec2u_from_rb(rb_size)));
}

.srgb_from_file(path) ⇒ Texture .srgb_from_file(path, area) ⇒ Texture

Loads an sRGB texture from the image file at filename.

Overloads:

Returns:

  • (Texture) —

    sRGB-encoded, loaded from the file at path, cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if loading fails



162
163
164
165
166
167
168
169
170
 
# File 'ext/graphics/texture.c', line 162

static VALUE Texture_srgb_from_file(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_path, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_path, &rb_area);

    return Texture_wrap(klass, sfTexture_createSrgbFromFile(StringValueCStr(rb_path),
                                                            Texture_area_ptr(rb_area, &area)));
}

.srgb_from_image(image) ⇒ Texture .srgb_from_image(image, area) ⇒ Texture

Creates an sRGB texture from the pixels of an existing Image.

Overloads:

Returns:

  • (Texture) —

    sRGB-encoded, built from image (an Image), cropped to area (a Rect) if given

Raises:

  • (TypeError) —

    if image is not an Image

  • (RuntimeError) —

    if creation fails



310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'ext/graphics/texture.c', line 310

static VALUE Texture_srgb_from_image(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_image, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_image, &rb_area);

    if (!rb_obj_is_kind_of(rb_image, Get_Klass_Image())) {
        raise_invalid_argument_class(Get_Klass_Image());
    }

    return Texture_wrap(klass, sfTexture_createSrgbFromImage(Get_Image_Struct(rb_image),
                                                             Texture_area_ptr(rb_area, &area)));
}

.srgb_from_memory(data) ⇒ Texture .srgb_from_memory(data, area) ⇒ Texture

Loads an sRGB texture from an in-memory image buffer.

Overloads:

Returns:

  • (Texture) —

    sRGB-encoded, decoded from the encoded image bytes in data (a String), cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if decoding fails



204
205
206
207
208
209
210
211
212
213
214
 
# File 'ext/graphics/texture.c', line 204

static VALUE Texture_srgb_from_memory(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_data, rb_area;
    sfIntRect area;

    rb_scan_args(argc, argv, "11", &rb_data, &rb_area);
    StringValue(rb_data);

    return Texture_wrap(klass, sfTexture_createSrgbFromMemory(RSTRING_PTR(rb_data),
                                                              (size_t)RSTRING_LEN(rb_data),
                                                              Texture_area_ptr(rb_area, &area)));
}

.srgb_from_stream(stream) ⇒ Texture .srgb_from_stream(stream, area) ⇒ Texture

Loads an sRGB texture from the image data read from stream.

Overloads:

Returns:

  • (Texture) —

    sRGB-encoded, decoded from stream (an InputStream), cropped to area (a Rect) if given

Raises:

  • (RuntimeError) —

    if decoding fails



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'ext/graphics/texture.c', line 255

static VALUE Texture_srgb_from_stream(int argc, VALUE* argv, VALUE klass) {
    VALUE rb_stream, rb_area, holder = Qnil;
    sfIntRect area;
    sfInputStream* stream;

    if (argc < 1 || argc > 2) {
        raise_invalid_arguments_excepted(2, argc);
    }

    rb_stream = argv[0];
    rb_area = (argc == 2) ? argv[1] : Qnil;
    stream = input_stream_from_rb(rb_stream, &holder);

    (void)holder;

    return Texture_wrap(klass,
                        sfTexture_createSrgbFromStream(stream, Texture_area_ptr(rb_area, &area)));
}

Instance Method Details

#bind ⇒ self #bind(coordinate_type) ⇒ self

Activates this texture for rendering. coordinate_type selects normalized (0..1) or pixel texture coordinates and defaults to normalized.

Overloads:

  • #bind ⇒ self

    Returns:

    • (self)
  • #bind(coordinate_type) ⇒ self

    Returns:

    • (self)

Returns:

  • (self) 


585
586
587
588
589
590
591
592
593
594
595
596
597
598
 
# File 'ext/graphics/texture.c', line 585

static VALUE Texture_bind(int argc, VALUE* argv, VALUE self) {
    VALUE rb_coordinate_type;
    sfCoordinateType type = sfCoordinateTypeNormalized;

    rb_scan_args(argc, argv, "01", &rb_coordinate_type);

    if (!NIL_P(rb_coordinate_type)) {
        type = coordinate_type_from_rb(rb_coordinate_type);
    }

    sfTexture_bind(Get_Texture_Struct(self), type);

    return self;
}

#copy ⇒ Texture

Returns a deep copy of the object.

Returns:

Returns:

  • (Texture) —

    an independent copy



330
331
332
 
# File 'ext/graphics/texture.c', line 330

static VALUE Texture_copy(VALUE self) {
    return Texture_wrap(Get_Klass_Texture(), sfTexture_copy(Get_Texture_Struct(self)));
}

#copy_to_image ⇒ Image

Copies the texture's pixels into image.

Returns:

Returns:

  • (Image) —

    the texture's pixels, read back from the GPU

Raises:

  • (RuntimeError) —

    if the copy fails



397
398
399
400
401
402
403
404
405
 
# File 'ext/graphics/texture.c', line 397

static VALUE Texture_copy_to_image(VALUE self) {
    sfImage* image = sfTexture_copyToImage(Get_Texture_Struct(self));

    if (image == NULL) {
        rb_raise(rb_eRuntimeError, "failed to copy texture to image");
    }

    return image_from_c(image);
}

#generate_mipmap ⇒ Boolean

Generates the mipmap pyramid for the texture.

Returns:

  • (Boolean)

Returns:

  • (Boolean) —

    whether mipmap generation succeeded



561
562
563
 
# File 'ext/graphics/texture.c', line 561

static VALUE Texture_generate_mipmap(VALUE self) {
    return BOOL2RB(sfTexture_generateMipmap((sfTexture*)Get_Texture_Struct(self)));
}

#native_handle ⇒ Integer

Returns the underlying OpenGL handle.

Returns:

  • (Integer)

Returns:

  • (Integer) —

    the underlying OpenGL texture handle



571
572
573
 
# File 'ext/graphics/texture.c', line 571

static VALUE Texture_get_native_handle(VALUE self) {
    return UINT2NUM(sfTexture_getNativeHandle(Get_Texture_Struct(self)));
}

#repeated=(value) ⇒ Boolean

Enables or disables texture repeating.

Returns:

  • (Boolean)

Returns:

  • (Boolean) —

    value



540
541
542
543
 
# File 'ext/graphics/texture.c', line 540

static VALUE Texture_set_repeated(VALUE self, VALUE rb_repeated) {
    sfTexture_setRepeated((sfTexture*)Get_Texture_Struct(self), RTEST(rb_repeated));
    return rb_repeated;
}

#repeated? ⇒ Boolean

Returns true if texture repeating is enabled.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


551
552
553
 
# File 'ext/graphics/texture.c', line 551

static VALUE Texture_is_repeated(VALUE self) {
    return BOOL2RB(sfTexture_isRepeated(Get_Texture_Struct(self)));
}

#resize(size) ⇒ Boolean

Resizes the texture in place. Existing pixel data is lost.

Returns:

  • (Boolean)

Returns:

  • (Boolean) —

    whether resizing succeeded



353
354
355
 
# File 'ext/graphics/texture.c', line 353

static VALUE Texture_resize(VALUE self, VALUE rb_size) {
    return BOOL2RB(sfTexture_resize((sfTexture*)Get_Texture_Struct(self), vec2u_from_rb(rb_size)));
}

#resize_srgb(size) ⇒ Boolean

Resizes the texture in place as sRGB-encoded. Existing pixel data is lost.

Returns:

  • (Boolean)

Returns:

  • (Boolean) —

    whether resizing succeeded



365
366
367
368
 
# File 'ext/graphics/texture.c', line 365

static VALUE Texture_resize_srgb(VALUE self, VALUE rb_size) {
    return BOOL2RB(
        sfTexture_resizeSrgb((sfTexture*)Get_Texture_Struct(self), vec2u_from_rb(rb_size)));
}

#size ⇒ Vector2

Returns the object's size.

Returns:

Returns:



340
341
342
343
344
 
# File 'ext/graphics/texture.c', line 340

static VALUE Texture_get_size(VALUE self) {
    sfVector2u size = sfTexture_getSize(Get_Texture_Struct(self));

    return vec2f_to_rb((sfVector2f){(float)size.x, (float)size.y});
}

#smooth=(value) ⇒ Boolean

Enables or disables smooth rendering.

Returns:

  • (Boolean)

Returns:

  • (Boolean) —

    value



508
509
510
511
 
# File 'ext/graphics/texture.c', line 508

static VALUE Texture_set_smooth(VALUE self, VALUE rb_smooth) {
    sfTexture_setSmooth((sfTexture*)Get_Texture_Struct(self), RTEST(rb_smooth));
    return rb_smooth;
}

#smooth? ⇒ Boolean

Returns true if smooth rendering is enabled.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


519
520
521
 
# File 'ext/graphics/texture.c', line 519

static VALUE Texture_is_smooth(VALUE self) {
    return BOOL2RB(sfTexture_isSmooth(Get_Texture_Struct(self)));
}

#srgb? ⇒ Boolean

Returns true if the texture uses an sRGB format.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


529
530
531
 
# File 'ext/graphics/texture.c', line 529

static VALUE Texture_is_srgb(VALUE self) {
    return BOOL2RB(sfTexture_isSrgb(Get_Texture_Struct(self)));
}

#swap(other) ⇒ self

Swaps the contents with other.

Returns:

  • (self)

Returns:

  • (self)

Raises:

  • (TypeError) —

    if other is not a Texture



380
381
382
383
384
385
386
387
388
 
# File 'ext/graphics/texture.c', line 380

static VALUE Texture_swap(VALUE self, VALUE rb_other) {
    if (!rb_obj_is_kind_of(rb_other, Get_Klass_Texture())) {
        raise_invalid_argument_class(Get_Klass_Texture());
    }

    sfTexture_swap((sfTexture*)Get_Texture_Struct(self), (sfTexture*)Get_Texture_Struct(rb_other));

    return self;
}

#update_from_image(image, offset) ⇒ self

Updates the texture from the pixels of image.

Returns:

  • (self)

Returns:

  • (self)

Raises:

  • (TypeError) —

    if image is not an Image



452
453
454
455
456
457
458
459
460
461
 
# File 'ext/graphics/texture.c', line 452

static VALUE Texture_update_from_image(VALUE self, VALUE rb_image, VALUE rb_offset) {
    if (!rb_obj_is_kind_of(rb_image, Get_Klass_Image())) {
        raise_invalid_argument_class(Get_Klass_Image());
    }

    sfTexture_updateFromImage((sfTexture*)Get_Texture_Struct(self), Get_Image_Struct(rb_image),
                              vec2u_from_rb(rb_offset));

    return self;
}

#update_from_pixels(pixels, size, offset) ⇒ self

Overwrites a size region of the texture at offset with pixels (a String of raw RGBA8 bytes, size.x * size.y * 4 long).

Returns:

  • (self)

Returns:

  • (self)

Raises:

  • (ArgumentError) —

    if pixels is shorter than required



416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'ext/graphics/texture.c', line 416

static VALUE Texture_update_from_pixels(VALUE self, VALUE rb_pixels, VALUE rb_size,
                                        VALUE rb_offset) {
    sfVector2u size = vec2u_from_rb(rb_size);
    sfVector2u offset = vec2u_from_rb(rb_offset);
    size_t expected;

    /* size.x * size.y * 4 as a bare size_t multiplication can wrap on the
       32-bit targets this gem ships; check before multiplying rather than
       after so a wrapped-to-near-zero "expected" can't slip a too-short
       buffer past the length check below (see the identical fix in
       graphics/image.c). */
    if (size.x != 0 && size.y > (SIZE_MAX / 4) / size.x) {
        rb_raise(rb_eArgError, "texture dimensions too large");
    }
    expected = (size_t)size.x * size.y * 4;

    StringValue(rb_pixels);

    if ((size_t)RSTRING_LEN(rb_pixels) < expected) {
        rb_raise(rb_eArgError, "pixel data too short");
    }

    sfTexture_updateFromPixels((sfTexture*)Get_Texture_Struct(self),
                               (const uint8_t*)RSTRING_PTR(rb_pixels), size, offset);

    return self;
}

#update_from_texture(source, offset) ⇒ self

Updates the texture from the pixels of another texture.

Returns:

  • (self)

Returns:

  • (self)

Raises:

  • (TypeError) —

    if source is not a Texture



471
472
473
474
475
476
477
478
479
480
 
# File 'ext/graphics/texture.c', line 471

static VALUE Texture_update_from_texture(VALUE self, VALUE rb_source, VALUE rb_offset) {
    if (!rb_obj_is_kind_of(rb_source, rb_cTexture)) {
        raise_invalid_argument_class(rb_cTexture);
    }

    sfTexture_updateFromTexture((sfTexture*)Get_Texture_Struct(self), Get_Texture_Struct(rb_source),
                                vec2u_from_rb(rb_offset));

    return self;
}

#update_from_window(window, offset) ⇒ self

Updates the texture from the contents of a window.

Returns:

  • (self)

Returns:

  • (self)

Raises:

  • (TypeError) —

    if window is not a Window



490
491
492
493
494
495
496
497
498
499
 
# File 'ext/graphics/texture.c', line 490

static VALUE Texture_update_from_window(VALUE self, VALUE rb_window, VALUE rb_offset) {
    if (!rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
        raise_invalid_argument_class(Get_Klass_Window());
    }

    sfTexture_updateFromRenderWindow((sfTexture*)Get_Texture_Struct(self),
                                     Get_Window_Struct(rb_window), vec2u_from_rb(rb_offset));

    return self;
}