Class: Snow::QuatArray

Inherits:

Data

• Object
• Data
• Snow::QuatArray

Includes:

ArrayMarshalSupport, ArraySupport, FiddlePointerSupport, InspectSupport

Defined in:

lib/snow-math/quat.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 Quats. 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.

Class Method Summary

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

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

Instance Method Summary

• #address ⇒ Object

  Returns the memory address of the object.

• #dup ⇒ Object (also: #clone)

  Duplicates the QuatArray and returns it.

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

  Fetches a Quat 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 Quat 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 Quat elements is allocated and returned. In the second form, a copy of a typed array of Quat objects is made and returned. Copied arrays do not share data.

call-seq:

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

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

static VALUE sm_quat_array_new(VALUE sm_self, VALUE sm_length_or_copy)
{
  size_t length = 0;
  quat_t *arr;
  VALUE sm_type_array;
  int copy_array = 0;
  if ((copy_array = SM_IS_A(sm_length_or_copy, quat_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(quat_t, length);
  if (copy_array) {
    const quat_t *source;
    Data_Get_Struct(sm_length_or_copy, quat_t, source);
    MEMCPY(arr, source, quat_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 QuatArray and returns it.

call-seq: dup -> new quat_array

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

def dup
  self.class.new(self)
end

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

Fetches a Quat from the array at the index and returns it. The returned Quat 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 Quat fetched from an array modifies the array’s data.

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

call-seq: fetch(index) -> quat

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

static VALUE sm_quat_array_fetch(VALUE sm_self, VALUE sm_index)
{
  quat_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, quat_t, arr);
    sm_inner = Data_Wrap_Struct(s_sm_quat_klass, 0, 0, arr[index]);
    rb_ivar_set(sm_inner, kRB_IVAR_MATHARRAY_SOURCE, sm_self);
    /* Store the Quat 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 884

static VALUE sm_quat_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 927

static VALUE sm_quat_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, quat_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 1052

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

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

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

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

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

static VALUE sm_quat_array_store(VALUE sm_self, VALUE sm_index, VALUE sm_value)
{
  quat_t *arr;
  quat_t *value;
  size_t length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  size_t index = NUM2SIZET(sm_index);

  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 (!SM_IS_A(sm_value, vec4) || !(SM_IS_A(sm_value, quat))) {
    rb_raise(rb_eTypeError,
      "Invalid value to store: expected Quat or Vec4, got %s",
      rb_obj_classname(sm_value));
  }

  Data_Get_Struct(sm_self, quat_t, arr);
  value = sm_unwrap_quat(sm_value, NULL);

  if (value == &arr[index]) {
    /* The object's part of the array, don't bother copying */
    return sm_value;
  }

  quat_copy(*value, arr[index]);
  return sm_value;
}