Class: Snow::Mat4Array

Inherits:
Object
  • Object
show all
Includes:
ArrayMarshalSupport, ArraySupport, FiddlePointerSupport, InspectSupport
Defined in:
lib/snow-math/mat4.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 Mat4s. 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 also be useful to subclass as a stack of Mat4s akin to now-deprecated functionality in OpenGL.

Class Method Summary collapse

Instance Method Summary collapse

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

call-seq:

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



921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
 
# File 'ext/snow-math/snow-math.c', line 921

static VALUE sm_mat4_array_new(VALUE sm_self, VALUE sm_length_or_copy)
{
  size_t length = 0;
  mat4_t *arr;
  VALUE sm_type_array;
  int copy_array = 0;
  if ((copy_array = SM_IS_A(sm_length_or_copy, mat4_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(mat4_t, length);
  if (copy_array) {
    const mat4_t *source;
    Data_Get_Struct(sm_length_or_copy, mat4_t, source);
    MEMCPY(arr, source, mat4_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



5564
5565
5566
5567
5568
5569
 
# File 'ext/snow-math/snow-math.c', line 5564

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

Duplicates the Mat4Array and returns it.

call-seq: dup -> new mat4_array



185
186
187
 
# File 'lib/snow-math/to_a.rb', line 185

def dup
  self.class.new(self)
end

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

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

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

call-seq: fetch(index) -> mat4



1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
 
# File 'ext/snow-math/snow-math.c', line 1010

static VALUE sm_mat4_array_fetch(VALUE sm_self, VALUE sm_index)
{
  mat4_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, mat4_t, arr);
    sm_inner = Data_Wrap_Struct(s_sm_mat4_klass, 0, 0, arr[index]);
    rb_ivar_set(sm_inner, kRB_IVAR_MATHARRAY_SOURCE, sm_self);
    /* Store the Mat4 in the cache */
    rb_ary_store(sm_cache, (long)index, sm_inner);
  }

  return sm_inner;
}

#length ⇒ Object

Returns the array’s length.

call-seq: length -> fixnum



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

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



969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
 
# File 'ext/snow-math/snow-math.c', line 969

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

  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, mat4_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



1092
1093
1094
1095
1096
 
# File 'ext/snow-math/snow-math.c', line 1092

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

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

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

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

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



1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
 
# File 'ext/snow-math/snow-math.c', line 1053

static VALUE sm_mat4_array_store(VALUE sm_self, VALUE sm_index, VALUE sm_value)
{
  mat4_t *arr;
  size_t length = NUM2SIZET(sm_mathtype_array_length(sm_self));
  size_t index = NUM2SIZET(sm_index);
  int is_mat4 = 0;

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

  Data_Get_Struct(sm_self, mat4_t, arr);

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