Module: STBI

Defined in:
ext/bindings.c

Constant Summary collapse

STBI_VERSION =

The version constant provided by stb_image.c

INT2FIX(STBI_VERSION)
COMPONENTS_DEFAULT =

Only valid for required_components arguments to load_image and load_float_image. See load_image for usage.

INT2FIX(STBI_default)
COMPONENTS_GREY =

Specifies that pixels in image data must have or has 1 component. See load_image for usage.

INT2FIX(STBI_grey)
COMPONENTS_GREY_ALPHA =

Specifies that pixels in image data must have or has 2 components. See load_image for usage.

INT2FIX(STBI_grey_alpha)
COMPONENTS_RGB =

Specifies that pixels in image data must have or has 3 components. See load_image for usage.

INT2FIX(STBI_rgb)
COMPONENTS_RGB_ALPHA =

Specifies that pixels in image data must have or has 4 components. See load_image for usage.

INT2FIX(STBI_rgb_alpha)

Class Method Summary collapse

Class Method Details

.load_float_image(io, required_components = COMPONENTS_DEFAULT) ⇒ Array .load_float_image(io, required_components = COMPONENTS_DEFAULT) {|info| ... } ⇒ Object

Similar to ::load_image, except the returned image data is a packaed string for an array of 32-bit floats (e.g., String#unpack(‘f*’) will extract an array of floating point values representing the components of the image’s pixels).

In the second form, the info array is yielded to the block if the image is successfully loaded. Otherwise, the method returns nil. This is possibly more convenient than doing an if info ... end block to check if the image was successfully loaded.

For further information on the IO object, the required_components argument, and so on, see the documentation for load_image.

Example

open('image.png') { |io|
  STBI.load_float_image(io) { |data, width, height, components|
    format = case components
             when STBI::COMPONENTS_GREY       then Gl::GL_RED
             when STBI::COMPONENTS_GREY_ALPHA then Gl::GL_RG
             when STBI_COMPONENTS_RGB         then Gl::RGB
             when STBI_COMPONENTS_RGB_ALPHA   then Gl::RGBA
             end

    Gl::glTexImage2D(Gl::GL_TEXTURE_2D, 0, format, width, height, 0,
                     format, Gl::GL_FLOAT, data)
  }
}

Overloads:

  • .load_float_image(io, required_components = COMPONENTS_DEFAULT) ⇒ Array

    Returns:

    • (Array)
  • .load_float_image(io, required_components = COMPONENTS_DEFAULT) {|info| ... } ⇒ Object

    Yields:

    • (info)

    Returns:

    • (Object) 


237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'ext/bindings.c', line 237

static VALUE sr_load_float_image(int argc, VALUE *argv, VALUE sr_self)
{
  VALUE sr_callbacks;
  VALUE sr_req_comp;
  VALUE sr_image_data = Qnil;
  int x = 0;
  int y = 0;
  int components[2] = {
    STBI_default,
    0
  };

  rb_scan_args(argc, argv, "11", &sr_callbacks, &sr_req_comp);

  if (NIL_P(sr_callbacks)) {
    rb_raise(rb_eArgError, "IO object cannot be nil");
    return Qnil;
  } if (RTEST(sr_req_comp)) {
    components[0] = FIX2INT(sr_req_comp);
  }

  float *data = stbi_loadf_from_callbacks(&s_st_callbacks, &sr_callbacks,
    &x, &y, &components[1], components[0]);

  if (data) {
    const long length = x * y * components[!components[0]] * sizeof(float);
    sr_image_data = rb_ary_new3(4,
      rb_external_str_new((const char *)data, length),
      INT2FIX(x), INT2FIX(y),
      INT2FIX(components[!components[0]]));
    stbi_image_free(data);
  }

  if (!NIL_P(sr_image_data) && rb_block_given_p()) {
    return rb_yield_splat(sr_image_data);
  } else {
    return sr_image_data;
  }
}

.load_image(io, required_components = COMPONENTS_DEFAULT) ⇒ Array .load_image(io, required_components = COMPONENTS_DEFAULT) {|info| ... } ⇒ Object

Loads an image using stb_image and returns the resulting data and its width, height, and the number of components per pixel in the data. The returned data is a packed string of unsigned 8-bit integers (8 bits per component). The length of the string will always be width * height * components.

In the second form, the info array is yielded to the block if the image is successfully loaded. Otherwise, the method returns nil. This is possibly more convenient than doing an if info ... end block to check if the image was successfully loaded.

IO Objects

IO objects accepted for loading data with must implement at least IO#read(length) and either IO#eof or IO#eof?. In addition, they may also implement a skip(length) method that skips length bytes and does not return any value. If the IO object does not respond to #skip, #read will be called instead and its result will be discarded. If you want to avoid unnecessary allocations, it may be wise to implement a skip method.

Components

If required_components is provided and not the default value, the image data returned will have as many components as are requested. In turn, the number of components returned via the array will be the same as required_components.

Valid options for required_components are:

::COMPONENTS_DEFAULT

The default value, loads as many components as are provided by the image.

::COMPONENTS_GREY

Loads only one component.

::COMPONENTS_GREY_ALPHA

Loads two components.

::COMPONENTS_RGB

Loads three components (red, green, and blue).

::COMPONENTS_RGB_ALPHA

Loads four components (red, green, blue, and alpha).

Example

open('image.png') { |io|
  STBI.load_image(io) { |data, width, height, components|
    format = case components
             when STBI::COMPONENTS_GREY       then Gl::GL_RED
             when STBI::COMPONENTS_GREY_ALPHA then Gl::GL_RG
             when STBI_COMPONENTS_RGB         then Gl::RGB
             when STBI_COMPONENTS_RGB_ALPHA   then Gl::RGBA
             end

    Gl::glTexImage2D(Gl::GL_TEXTURE_2D, 0, format, width, height, 0,
                     format, Gl::GL_UNSIGNED_BYTE, data)
  }
}

Overloads:

  • .load_image(io, required_components = COMPONENTS_DEFAULT) ⇒ Array

    Returns:

    • (Array)
  • .load_image(io, required_components = COMPONENTS_DEFAULT) {|info| ... } ⇒ Object

    Yields:

    • (info)

    Returns:

    • (Object) 


158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'ext/bindings.c', line 158

static VALUE sr_load_image(int argc, VALUE *argv, VALUE sr_self)
{
  VALUE sr_callbacks;
  VALUE sr_req_comp;
  VALUE sr_image_data = Qnil;
  int x = 0;
  int y = 0;
  int components[2] = {
    STBI_default,
    0
  };

  rb_scan_args(argc, argv, "11", &sr_callbacks, &sr_req_comp);

  if (NIL_P(sr_callbacks)) {
    rb_raise(rb_eArgError, "IO object cannot be nil");
    return Qnil;
  } if (RTEST(sr_req_comp)) {
    components[0] = FIX2INT(sr_req_comp);
  }

  if (!rb_obj_respond_to(sr_callbacks, s_read_funcid, 0) ||
      !(rb_obj_respond_to(sr_callbacks, s_eof_funcid, 0) ||
        rb_obj_respond_to(sr_callbacks, s_eof_qm_funcid, 0))) {
    rb_raise(rb_eTypeError, "IO object does not respond to either read or eof/eof?");
  }

  stbi_uc *data = stbi_load_from_callbacks(&s_st_callbacks, &sr_callbacks,
    &x, &y, &components[1], components[0]);

  if (data) {
    const long length = x * y * components[!components[0]];
    sr_image_data = rb_ary_new3(4,
      rb_external_str_new((const char *)data, length),
      INT2FIX(x), INT2FIX(y),
      INT2FIX(components[!components[0]]));
    stbi_image_free(data);
  }

  if (!NIL_P(sr_image_data) && rb_block_given_p()) {
    return rb_yield_splat(sr_image_data);
  } else {
    return sr_image_data;
  }
}

.set_hdr_to_ldr_gamma(value) ⇒ Object .hdr_to_ldr_gamma=(value) ⇒ Object

Sets the HDR to LDR gamma used when loading HDR images with load_image.



284
285
286
287
288
 
# File 'ext/bindings.c', line 284

static VALUE sr_set_hdr_to_ldr_gamma(VALUE self, VALUE gamma)
{
  stbi_hdr_to_ldr_gamma((float)NUM2DBL(gamma));
  return gamma;
}

.set_hdr_to_ldr_scale(value) ⇒ Object .hdr_to_ldr_scale=(value) ⇒ Object

Sets the HDR to LDR scale used when loading HDR images with load_image.



297
298
299
300
301
 
# File 'ext/bindings.c', line 297

static VALUE sr_set_hdr_to_ldr_scale(VALUE self, VALUE scale)
{
  stbi_hdr_to_ldr_scale((float)NUM2DBL(scale));
  return scale;
}

.set_ldr_to_hdr_gamma(value) ⇒ Object .ldr_to_hdr_gamma=(value) ⇒ Object

Sets the LDR to HDR gamma used when loading LDR images with load_float_image.



310
311
312
313
314
 
# File 'ext/bindings.c', line 310

static VALUE sr_set_ldr_to_hdr_gamma(VALUE self, VALUE gamma)
{
  stbi_ldr_to_hdr_gamma((float)NUM2DBL(gamma));
  return gamma;
}

.set_ldr_to_hdr_scale(value) ⇒ Object .ldr_to_hdr_scale=(value) ⇒ Object

Sets the LDR to HDR scale used when loading LDR images with load_float_image.



323
324
325
326
327
 
# File 'ext/bindings.c', line 323

static VALUE sr_set_ldr_to_hdr_scale(VALUE self, VALUE scale)
{
  stbi_ldr_to_hdr_scale((float)NUM2DBL(scale));
  return scale;
}