-
Notifications
You must be signed in to change notification settings - Fork 29
Using vectors
There are dozens of ways of constructing a vector.
For simplicity, if the same initialization process applies to all vector types, it will only be shown for glm.vec2.
Initializing a vector without any additional arguments will set all of it's components to zero (of the respective type).
i.e. glm.vec2() returns vector (0.0, 0.0).
A boolean vector would also be initialized with zero (or False if you will).
Initializing a vector with a number will set all of it's components to the given number (which may be converted if necessary).
i.e. glm.vec2(2.43) returns vector (2.43, 2.43).
A vector vecN can be initialized with N numbers, which will be copied (or may be converted) to their components.
i.e. glm.vec2(1, 2) returns vector (1.0, 2.0)
glm.vec3(4, 5, 6) returns vector (4.0, 5.0, 6.0)
glm.ivec4(9, 8, 7, 6) returns vector (9, 8, 7, 6)
A copy of a vector can be obtained by initializing a vector with an instance of a vector.
i.e. glm.vec2(glm.vec2(3, 2)) returns vector (3.0, 2.0)
This is what's known as the copy constructor.
You can initialize any vector with a larger vector (which will discard any values that don't fit into the new vector).
i.e. glm.vec1(glm.vec3(1, 2, 3)) returns vector (1.0)
likewise glm.vec2(glm.vec4(5, 6, 7, 8)) returns vector (5.0, 6.0)
As long as you don't use any vec1s in your equation, you can construct any vector from a combination of vectors and / or numbers if their sum equals the length of the target vector.
i.e. glm.vec4(glm.vec2(1, 2), 3, 4) returns vector (1.0, 2.0, 3.0, 4.0)
likewise glm.vec3(5, glm.vec2(4, 3)) returns vector (5.0, 4.0, 3.0)
but glm.vec2(glm.vec1(1), 2) doesn't work.
glm.vec3(glm.vec2(1, 2), glm.vec2(3, 4)) also doesn't work.
Instead of using vectors to initialize vectors, you can also use lists and other iterables.
e.g. glm.vec2([1, 2]) returns vector (1.0, 2.0)
or glm.vec3((3, 4), 5) returns vector (3.0, 4.0, 5.0)
A few objects in Python support a functionality called the buffer protocol.
One such example would be the Python bytes type or numpy.array.
PyGLM also supports this protocol and thus can be converted to or from any other object that supports it, granted it's in a fitting format.
e.g. bytes(glm.u8vec2(1,2)) returns b'\x01\x02'
and glm.u8vec2(b'\x01\x02') returns an 8-bit unsigned integer vector (1, 2)
or glm.vec3(numpy.array([4,5,6])) returns vector (4.0, 5.0, 6.0)
and numpy.array(glm.vec3(4, 5, 6)) returns array([4., 5., 6.], dtype=float32)
Note: objects that use the buffer protocol may request a reference instead of a copy of the object, meaning that if you change the 'copy', you'll also change the original.
A vector has a member for each of it's values.
vec1 has members: (x)
vec2 has members: (x, y)
vec3 has members: (x, y, z)
vec4 has members: (x, y, z, w)
Using swizzling, you can also construct vectors from up to four members:
v = vec4(1, 2, 3, 4)
v2 = v.xy # returns vec2(1, 2)
v3 = v.zw # returns vec2(3, 4)
v4 = v.xxxw # returns vec4(1, 1, 1, 4)Any vector type implements the following methods:
Vectors support the copy protocol (see here).
You can use copy.copy(<vector>) or copy.deepcopy(<vector>) to get a copy of a vector.
Vectors support pickling (as of PyGLM 2.0.0), which is Python's serialization method.
Any vector type has a to_list() and a to_tuple() function, which return's the vector's data represented as a list or tuple respectively.
All vectors have a to_bytes() and a from_bytes() method, which allows for conversion of the vector's data to and from bytes strings.
Vector types support a lot of operators.
Vectors support addition with other vectors and numbers.
sum1 = vec2(1, 2) + vec2(4, 0) # returns vec2(5, 2)
sum2 = vec2(1, 2) + 4 # returns vec2(5, 6)Vectors support subtraction with other vectors and numbers.
diff1 = vec2(1, 2) - vec2(4, 0) # returns vec2(-3, 2)
diff2 = vec2(1, 2) - 4 # returns vec2(-3, -2)Vectors support multiplication with other vectors and numbers.
prod1 = vec2(1, 2) * vec2(4, 0) # returns vec2(4, 0)
prod2 = vec2(1, 2) * 4 # returns vec2(4, 8)Has the same effects as the * operator, but with the arguments switched.
I.e. a * b == b @ a
Vectors support division with other vectors and numbers.
quot1 = vec2(1, 2) / vec2(4, 0.5) # returns vec2(0.25, 4 )
quot2 = vec2(1, 2) / 4 # returns vec2(0.25, 0.5)Vectors support modulo operations with other vectors and numbers.
mod1 = vec2(1, 2) % vec2(4, 2) # returns vec2(1, 0)
mod2 = vec2(1, 2) % 4 # returns vec2(1, 2)Vectors support floored division with other vectors and numbers.
fquot1 = vec2(1, 2) // vec2(4, 0.5) # returns vec2(0, 4)
fquot2 = vec2(1, 2) // 4 # returns vec2(0, 0)Vectors support combined floor division and modulo operations with other vectors and numbers.
divmod1 = divmod(vec2(1, 2), vec2(4, 2)) # returns (vec2(0, 1), vec2(1, 0))
divmod2 = divmod(vec2(1, 2), 4) # returns (vec2(0, 0), vec2(1, 2))Integer vectors support the bitwise left shift operator.
>>> ivec3(1, 2, 3) << 4
ivec3( 16, 32, 48 )
>>> uvec3(1, 2, 3) << uvec3(1, 2, 3)
uvec3( 2, 8, 24 )Integer vectors support the bitwise right shift operator.
>>> ivec3(16, 32, 48) >> 4
ivec3( 1, 2, 3 )
>>> uvec3(2, 8, 24) >> uvec3(1, 2, 3)
uvec3( 1, 2, 3 )Integer vectors support the bitwise and operator.
>>> ivec3(1, 2, 3) & 2
ivec3( 0, 2, 2 )
>>> uvec3(1, 2, 3) & uvec3(3, 2, 1)
uvec3( 1, 2, 1 )Integer vectors support the bitwise or operator.
>>> ivec3(1, 2, 3) | 2
ivec3( 3, 2, 3 )
>>> uvec3(1, 2, 3) | uvec3(6, 5, 4)
uvec3( 7, 7, 7 )Integer vectors support the bitwise xor operator.
>>> ivec3(1, 2, 3) ^ 2
ivec3( 3, 0, 1 )
>>> uvec3(1, 2, 3) ^ uvec3(3, 2, 1)
uvec3( 2, 0, 2 )Vectors support pow operations with other vectors and numbers.
pow1 = vec2(1, 2) ** vec2(4, 2) # returns vec2(1, 4)
pow2 = vec2(1, 2) ** 4 # returns vec2(1, 16)The length of a vector can be queried using len().
vec_length = len(vec2()) # returns 2You can get the values of a vector using indices.
v = vec2(1, 2)
print(v[0]) # prints 1.0
print(v[1]) # prints 2.0Likewise you can set the values.
v = vec2(1, 2)
v[0] = 9
print(v.x) # prints 9.0You can query wether or not a value is contained by a vector using the in operator.
v = vec2(1, 2)
true = 2 in v
false = 2.01 in vYou can compare vectors using the richcompare operators:
vec2(1, 2) == vec2(1, 2) # True
vec2(1, 2) == vec2(2, 2) # False
vec2(1, 2) == vec3(1, 2, 3) # False
vec2(1, 2) != vec2(1, 2) # False
vec2(1, 2) != vec2(2, 2) # True
vec2(1, 2) != vec3(1, 2, 3) # True
vec2(1, 2) < vec2(5, 5) # vec2(1, 1)
vec2(1, 2) < vec2(2, 2) # vec2(1, 0)
vec2(1, 2) < vec2(0, 0) # vec2(0, 0)
vec2(1, 2) <= vec2(5, 5) # vec2(1, 1)
vec2(1, 2) <= vec2(2, 2) # vec2(1, 1)
vec2(1, 2) <= vec2(0, 0) # vec2(0, 0)
vec2(1, 2) > vec2(5, 5) # vec2(0, 0)
vec2(1, 2) > vec2(2, 2) # vec2(0, 0)
vec2(1, 2) > vec2(0, 0) # vec2(1, 1)
vec2(1, 2) >= vec2(5, 5) # vec2(0, 0)
vec2(1, 2) >= vec2(2, 2) # vec2(0, 1)
vec2(1, 2) >= vec2(0, 0) # vec2(1, 1)You can generate an iterable from vectors using iter().
v = vec2(1, 2)
it = iter(v)
print(next(it)) # prints 1.0
print(next(it)) # prints 2.0You can generate a hash value for vectors using hash()
Example:
>>> v = vec2()
>>> hash(v)
-1952026010959490761
>>> v2 = vec2(1, 2)
>>> hash(v2)
8639716006723752019
>>> v3 = v2 * 0
>>> hash(v3)
-1952026010959490761