-
Notifications
You must be signed in to change notification settings - Fork 29
Using arrays
PyGLM's array type was introduced in version 2.0.0 to reduce the likelihood of requiring users to also use numpy besides glm.
It's mainly intended to provide a way of passing multiple glm type instances (such as vectors) to external C functions
(such as glBufferData).
PyGLM's arrays are pure data copies of one or multiple instances of a single PyGLM type.
For example, an array could copy the data of five different vec3 instances.
However, it cannot copy the data of instances, that don't have the same type, like two vec2 instances and one dvec2 instance.
Additionally, the data inside the array is only a copy, thus if the data inside the array is modified, it won't affect the instances it copied the data from.
Arrays can be initialized in a few different ways.
An array can be initialized with any number of vectors, metrices or quaternions, as long as they're all of the same type.
>>> array(vec3(1, 2, 3), vec3(4, 5, 6))
array(vec3(1, 2, 3), vec3(4, 5, 6))
>>> array(vec3(), ivec3())
TypeError: arrays have to be initialized with arguments of the same glm typeThe same holds true for ctypes numbers:
>>> array(int8(2), int8(3))
array(c_int8(2), c_int8(3))
>>> array(int8(2), int16(3))
TypeError: arrays have to be initialized with arguments of the same typeYou can also create an array of ctypes numbers from normal numbers using from_numbers, which needs to have the data type as it's first argument:
>>> array.from_numbers(int8, 2, 3)
array(c_int8(2), c_int8(3))
>>> array(int8, 2, 3) # alternative way
array(c_int8(2), c_int8(3))Note: The list representations of vecs, mats and quats such as ((1, 2), (3, 4)) (an alias for mat2(1, 2, 3, 4)) cannot be used here.
You can obtain a copy of an array by using the copy constructor.
arr_copy = array(arr)You can convert any compatible type to a PyGLM array.
This includes lists, tuples, etc. and types that support the buffer protocol (such as numpy's arrays):
>>> array((ivec1(), ivec1()))
array(ivec1(0), ivec1(0))
>>> array([dmat2()])
array(dmat2x2((1, 0), (0, 1)))
>>> array(numpy.array([[1,2,3]]))
array(ivec3(1, 2, 3))
>>> array([[1,2,3]])
TypeError: invalid argument type(s) for array()Note: array buffers that store length 4 items are interpreted as vec4s rather than quats.
PyGLM arrays have the following members:
| Name | Type | Description |
|---|---|---|
| element_type | type | Type class of the contained elements (e.g. glm.vec3) |
| length | int | Number of elements contained by a given array |
| address | int | The memory address where an array's data is stored |
| ptr | c_void_p | A ctypes pointer that points to the content of an array |
| nbytes | int | The total data size in bytes |
| typecode | str | A single character, describing the data type of the elements' values, according to this list |
| dtype | str | A numpy-like data type string |
| itemsize | int | The size of one array element in bytes |
| dt_size | int | The size of each single component of the elements in bytes (size of data type) |
Arrays support the copy protocol (see here).
You can use copy.copy(<array>) or copy.deepcopy(<array>) to get a copy of an array.
Arrays support pickling (as of PyGLM 2.0.0), which is Python's serialization method.
Any array has a to_list() and a to_tuple() function, which return's the arrays's data represented as a list or tuple respectively.
The array class has a static from_numbers method, which allows for creation of a one-dimensional array of numbers.
It takes a ctypes number type as it's first argument.
Example:
>>> array.from_numbers(c_float, 1.2, 3.4)
array(c_float(1.2), c_float(3.4))
>>> array.from_numbers(int32, 1, 3, 4, 5)
array(c_int32(1), c_int32(3), c_int32(4), c_int32(5))Arrays can be combined / concaternated using the + operator, as long as they have the same element type.
>>> array(vec2(1, 2)) + array(vec2(3, 4))
array(vec2(1, 2), vec2(3, 4))
>>> array(vec4()) + array(vec1())
ValueError: the given arrays are incompatibleArrays can be repeated a given number of times using the * operator.
>>> array(vec3(1, 2, 3)) * 3
array(vec3(1, 2, 3), vec3(1, 2, 3), vec3(1, 2, 3))You can access the individual elements of an array using indices.
Likewise you can also modify it's data by overwriting it or delete it using del
>>> arr = array(vec1(1), vec1(2), vec1(3))
>>> arr[0]
vec1( 1 )
>>> arr[1] = vec1(0)
>>> arr
array(vec1(1), vec1(0), vec1(3))
>>> del arr[2]
>>> arr
array(vec1(1), vec1(0))You can also use slices to get or modify sub-arrays:
>>> arr = array(vec1(1), vec1(2), vec1(3), vec1(4))
>>> arr[:2]
array(vec1(1), vec1(2))
>>> arr[::2]
array(vec1(1), vec1(3))
>>> del arr[1:3]
>>> arr
array(vec1(1), vec1(4))
>>> arr[:] = array(vec1(8), vec1(9))
>>> arr
array(vec1(8), vec1(9))Slices have the following syntax: start_index : stop_index : optional_step, meaning you start at start and go step steps until you've reached or passed stop (exclusive) or the greatest possible index.
You can check wether or not an element is present in the array using the in operator.
>>> arr = array(vec2(1, 2), vec2(3, 4))
>>> vec2() in arr
False
>>> vec2(3, 4) in arr
True
>>> vec2(2, 3) in arr
FalseYou can acquire the length of an array using the built-in len() function.
>>> len(array(vec1(0), vec1(1)))
2
>>> len(array(vec2(0, 1), vec2(2, 3), vec2(4, 5)))
3You can get a string representation of an array using the built-in str() function.
Example:
>>> print(str(array(vec2(1, 2), vec2(3, 4), vec2(5, 6))))
[
[ 1, 2 ],
[ 3, 4 ],
[ 5, 6 ],
]
>>> print(str(array(mat2(1, 2, 3, 4), mat2(5, 6, 7, 8))))
[
[
[ 1, 2 ],
[ 3, 4 ],
],
[
[ 5, 6 ],
[ 7, 8 ],
],
]You can get a reproducable string representation of an array using the built-in str() function.
Example:
>>> print(repr(array(vec2(1, 2), vec2(3, 4), vec2(5, 6))))
array(vec2(1, 2), vec2(3, 4), vec2(5, 6))
>>> print(repr(array(mat2(1, 2, 3, 4), mat2(5, 6, 7, 8))))
array(mat2x2((1, 2), (3, 4)), mat2x2((5, 6), (7, 8)))You can get an iterator from an array using iter()
>>> arr = array(vec2(1, 2), vec2(3, 4))
>>> it = iter(arr)
>>> next(it)
vec2( 1, 2 )
>>> next(it)
vec2( 3, 4 )You can generate a hash value for arrays using hash()
Example:
>>> arr = array(vec3(1), vec3(2), vec3(3), vec3(4))
>>> hash(arr)
-2624592468369027458
>>> arr2 = array(vec3(1), vec3(2), vec3(3))
>>> hash(arr2)
9163283608357050393
>>> arr3 = arr2 + array(vec3(4))
>>> hash(arr3)
-2624592468369027458