Class: Snow::Mat3Array

Inherits:

Data

• Object
• Data
• Snow::Mat3Array

Includes:

ArrayMarshalSupport, ArraySupport, FiddlePointerSupport, InspectSupport

Defined in:

lib/snow-math/mat3.rb,
lib/snow-math/ptr.rb,
lib/snow-math/to_a.rb,
lib/snow-math/inspect.rb,
lib/snow-math/marshal.rb,
ext/snow-math/snow-math.c

Overview

A contiguous array of Mat3s. Allocated as a single block of memory so that it can easily be passed back to C libraries (like OpenGL) and to aid with cache locality.

May be useful when subclassed as a stack to recreate now-drepcated OpenGL functionality, though perhaps less-so than a Mat4 stack.

Class Method Summary

• .new(sm_length_or_copy) ⇒ Object (also: [])

  In the first form, a new typed array of Mat3 elements is allocated and returned.

Instance Method Summary

• #address ⇒ Object

  Returns the memory address of the object.

• #dup ⇒ Object (also: #clone)

  Duplicates the Mat3Array and returns it.

• #fetch(sm_index) ⇒ Object (also: #[])

  Fetches a Mat3 from the array at the index and returns it.

• #freeze ⇒ Object

  Freezes the array and its elements.

• #length ⇒ Object

  Returns the array’s length.

• #resize!(sm_new_length) ⇒ Object

  Resizes the array to new_length and returns self.

• #size ⇒ Object

  Returns the length of the array.

• #store(sm_index, sm_value) ⇒ Object (also: #[]=)

  Stores a Mat3 at the given index.

Methods included from ArrayMarshalSupport

#_dump, included

Methods included from InspectSupport

#inspect

Methods included from ArraySupport

#each, #map, #map!, #to_a

Methods included from FiddlePointerSupport

#to_ptr

Class Method Details

.new(sm_length_or_copy) ⇒ Object Also known as: []

In the first form, a new typed array of Mat3 elements is allocated and returned. In the second form, a copy of a typed array of Mat3 objects is made and returned. Copied arrays do not share data.

call-seq:

new(size)       -> new mat3_array
new(mat3_array) -> copy of mat3_array

# File 'ext/snow-math/snow-math.c', line 1077

static VALUE sm_mat3_array_new(VALUE sm_self, VALUE sm_length_or_copy)
{
  size_t length = 0;
  mat3_t *arr;
  VALUE sm_type_array;
  int copy_array = 0;
  if ((copy_array = SM_IS_A(sm_length_or_copy, mat3_array))) {
    length = NUM2SIZET(sm_mathtype_array_length(sm_length_or_copy));
  } else {
    length = NUM2SIZET(sm_length_or_copy);
  }
  if (length <= 0) {
    return Qnil;
  }
  arr = ALLOC_N(mat3_t, length);
  if (copy_array) {
    const mat3_t *source;
    Data_Get_Struct(sm_length_or_copy, mat3_t, source);
    MEMCPY(arr, source, mat3_t, length);
    sm_length_or_copy = sm_mathtype_array_length(sm_length_or_copy);
    sm_self = rb_obj_class(sm_length_or_copy);
  }
  sm_type_array = Data_Wrap_Struct(sm_self, 0, free, arr);
  rb_ivar_set(sm_type_array, kRB_IVAR_MATHARRAY_LENGTH, sm_length_or_copy);
  rb_ivar_set(sm_type_array, kRB_IVAR_MATHARRAY_CACHE, rb_ary_new2((long)length));
  rb_obj_call_init(sm_type_array, 0, 0);
  return sm_type_array;
}

Instance Method Details

#address ⇒ Object

Returns the memory address of the object.

call-seq: address -> fixnum

# File 'ext/snow-math/snow-math.c', line 6894

static VALUE sm_get_address(VALUE sm_self)
{
  void *data_ptr = NULL;
  Data_Get_Struct(sm_self, void, data_ptr);
  return ULL2NUM((unsigned long long)data_ptr);
}

#dup ⇒ Object Also known as: clone

Duplicates the Mat3Array and returns it.

call-seq: dup -> new mat3_array

# File 'lib/snow-math/to_a.rb', line 194

def dup
  self.class.new(self)
end

#fetch(sm_index) ⇒ Object Also known as: []

Fetches a Mat3 from the array at the index and returns it. The returned Mat3 may be a cached object. In all cases, values returned from a typed array are associated with the memory of the array and not given their own memory. So, modifying a Mat3 fetched from an array modifies the array’s data.

As a result, objects returned by a Mat3Array should not be considered thread-safe, nor should manipulating a Mat3Array be considered thread-safe either. If you want to work with data returned from an array without altering the array data, you should call Mat3#dup or Mat3#copy to get a new Mat3 with a copy of the array object’s data.

call-seq: fetch(index) -> mat3

# File 'ext/snow-math/snow-math.c', line 1199

static VALUE sm_mat3_array_fetch(VALUE sm_self, VALUE sm_index)
{
  mat3_t *arr;
  size_t length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  size_t index = NUM2SIZET(sm_index);
  VALUE sm_inner;
  VALUE sm_cache;
  if (index >= length) {
    rb_raise(rb_eRangeError,
      "Index %zu out of bounds for array with length %zu",
      index, length);
  }

  sm_cache = rb_ivar_get(sm_self, kRB_IVAR_MATHARRAY_CACHE);
  if (!RTEST(sm_cache)) {
    rb_raise(rb_eRuntimeError, "No cache available");
  }
  sm_inner = rb_ary_entry(sm_cache, (long)index);

  if (!RTEST(sm_inner)) {
    /* No cached value, create one. */
    Data_Get_Struct(sm_self, mat3_t, arr);
    sm_inner = Data_Wrap_Struct(s_sm_mat3_klass, 0, 0, arr[index]);
    rb_ivar_set(sm_inner, kRB_IVAR_MATHARRAY_SOURCE, sm_self);
    /* Store the Mat3 in the cache */
    rb_ary_store(sm_cache, (long)index, sm_inner);
  }

  if (OBJ_FROZEN(sm_self)) {
    rb_funcall2(sm_inner, kRB_NAME_FREEZE, 0, 0);
  }

  return sm_inner;
}

#freeze ⇒ Object

Freezes the array and its elements.

call-seq: freeze -> self

# File 'ext/snow-math/snow-math.c', line 1113

static VALUE sm_mat3_array_freeze(VALUE sm_self)
{
  VALUE sm_cache;
  VALUE sm_cached_entry;
  long length;
  long index;

  if (OBJ_FROZEN(sm_self)) {
    return sm_self;
  }

  sm_cache = rb_ivar_get(sm_self, kRB_IVAR_MATHARRAY_CACHE);
  length = RARRAY_LEN(sm_cache);

  for (index = 0; index < length; ++index) {
    sm_cached_entry = rb_ary_entry(sm_cache, index);
    if (RTEST(sm_cached_entry)) {
      rb_funcall2(sm_cached_entry, kRB_NAME_FREEZE, 0, 0);
    }
  }

  return rb_call_super(0, 0);
}

#length ⇒ Object

Returns the array’s length.

call-seq: length -> fixnum

# File 'ext/snow-math/snow-math.c', line 85

static VALUE sm_mathtype_array_length(VALUE sm_self)
{
  return rb_ivar_get(sm_self, kRB_IVAR_MATHARRAY_LENGTH);
}

#resize!(sm_new_length) ⇒ Object

Resizes the array to new_length and returns self.

If resizing to a length smaller than the previous length, excess array elements are discarded and the array is truncated. Otherwise, when resizing the array to a greater length than previous, new elements in the array will contain garbage values.

If new_length is equal to self.length, the call does nothing to the array.

Attempting to resize an array to a new length of zero or less will raise a RangeError. Do not try to resize arrays to zero or less. Do not be that person.

call-seq:

resize!(new_length) -> self

# File 'ext/snow-math/snow-math.c', line 1156

static VALUE sm_mat3_array_resize(VALUE sm_self, VALUE sm_new_length)
{
  size_t new_length;
  size_t old_length;

  rb_check_frozen(sm_self);

  old_length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  new_length = NUM2SIZET(sm_new_length);

  if (old_length == new_length) {
    /* No change, done */
    return sm_self;
  } else if (new_length < 1) {
    /* Someone decided to be that person. */
    rb_raise(rb_eRangeError,
      "Cannot resize array to length less than or equal to 0.");
    return sm_self;
  }

  REALLOC_N(RDATA(sm_self)->data, mat3_t, new_length);
  rb_ivar_set(sm_self, kRB_IVAR_MATHARRAY_LENGTH, sm_new_length);
  rb_ary_clear(rb_ivar_get(sm_self, kRB_IVAR_MATHARRAY_CACHE));

  return sm_self;
}

#size ⇒ Object

Returns the length of the array.

call-seq: length -> fixnum

# File 'ext/snow-math/snow-math.c', line 1287

static VALUE sm_mat3_array_size(VALUE sm_self)
{
  size_t length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  return SIZET2NUM(length * sizeof(mat3_t));
}

#store(sm_index, sm_value) ⇒ Object Also known as: []=

Stores a Mat3 at the given index. If the provided Mat3 is a member of the array and stored at the index, then no copy is done, otherwise the Mat3 is copied to the array.

If the value stored is a Mat4, it will be converted to a Mat3 for storage, though this will not modify the value directly.

call-seq: store(index, value) -> value

# File 'ext/snow-math/snow-math.c', line 1246

static VALUE sm_mat3_array_store(VALUE sm_self, VALUE sm_index, VALUE sm_value)
{
  mat3_t *arr;
  size_t length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  size_t index = NUM2SIZET(sm_index);
  int is_mat3 = 0;

  rb_check_frozen(sm_self);

  if (index >= length) {
    rb_raise(rb_eRangeError,
      "Index %zu out of bounds for array with length %zu",
      index, length);
  } else if (!(is_mat3 = SM_IS_A(sm_value, mat3)) && !SM_IS_A(sm_value, mat4)) {
    rb_raise(rb_eTypeError,
      "Invalid value to store: expected Mat3 or Mat4, got %s",
      rb_obj_classname(sm_value));
  }

  Data_Get_Struct(sm_self, mat3_t, arr);

  if (is_mat3) {
    mat3_t *value = sm_unwrap_mat3(sm_value, NULL);
    if (value == &arr[index]) {
      /* The object's part of the array, don't bother copying */
      return sm_value;
    }
    mat3_copy(*value, arr[index]);
  } else {
    mat4_to_mat3(*sm_unwrap_mat4(sm_value, NULL), arr[index]);
  }
  return sm_value;
}