.. _vec4:

vec4 - 4d vector
----------------

A :class:`vec4` represents a 4D vector type. You can construct a :class:`vec4`
by several ways::

   # all components are set to zero
   v = vec4()

   -> (0.0000, 0.0000, 0.0000, 0.0000)

   # set all components to one value
   v = vec4(2.5)

   -> (2.5000, 2.5000, 2.5000, 2.5000)

   # set a 2d vector, the ramaining components will be zero
   v = vec4(1.5, 0.8)

   -> (1.5000, 0.8000, 0.0000, 0.0000)

   # set a 3d vector, the ramaining component will be zero
   v = vec4(1.5, 0.8, -0.5)

   -> (1.5000, 0.8000, -0.5000, 0.0000)

   # set all components
   v = vec4(1.5, 0.8, -0.5, 0.2)

   -> (1.5000, 0.8000, -0.5000, 0.2000)

Additionally you can use all of the above, but store the values inside a tuple,
a list or a string::

   v = vec4([1.5, 0.8, -0.5])
   w = vec4("1.5, 0.8")

Finally, you can initialize a vector with a copy of another vector::

   v = vec4(w)

A :class:`vec4` can be used just like a list with 4 elements, so you can read
and write components using the index operator or by accessing the components by
name::

   >>> v=vec4(1,2,3,1)
   >>> print v[0]
   1.0
   >>> print v.y
   2.0
   >>> print v.w
   1.0
   >>> print v.t   # this is the same as v.w
   1.0

The 4th component can be accessed either by the name ``w`` or ``t``. You might
prefer the former name when using the vector as a homogenous coordinate while
the latter might be preferable when the 4th component shall represent a time
value.

**Mathematical operations:**

The mathematical operators are supported with the following combination of
types::

   vec4  =  vec4 + vec4
   vec4  =  vec4 - vec4
   float =  vec4 * vec4      # dot product
   vec4  = float * vec4
   vec4  =  vec4 * float
   vec4  =  vec4 / float
   vec4  =  vec4 % float     # each component
   vec4  =  vec4 % vec4      # component wise
   vec4  = -vec4
   float =  vec4[i]          # get or set element

Additionally, you can compare vectors with ``==``, ``!=``, ``<``,  ``<=``,
``>``, ``>=``. Each comparison (except ``<`` and ``>``) takes an epsilon
environment into account, this means two values are considered to be equal if
their absolute difference is less than or equal to a threshold value epsilon.
You can read and write this threshold value using the functions
:func:`getEpsilon` and :func:`setEpsilon`.

Taking the absolute value of a vector will return the length of the vector::

   float = abs(v)            # this is equivalent to v.length()


.. class:: vec4([args])


   .. method:: vec4.length()

      Returns the length of the vector (:math:`\sqrt{x^2+y^2+z^2+w^2}`). This is
      equivalent to calling ``abs(self)``.


   .. method:: vec4.normalize()

      Returns normalized vector. If the method is called on the null vector (where
      each component is zero) a :exc:`ZeroDivisionError` is raised.


   .. method:: vec4.min()

      Returns the minimum value of the components.


   .. method:: vec4.max()

      Returns the maximum value of the components.


   .. method:: vec4.minIndex()

      Return the index of the component with the minimum value.


   .. method:: vec4.maxIndex()

      Return the index of the component with the maximum value.


   .. method:: vec4.minAbs()

      Returns the minimum absolute value of the components.


   .. method:: vec4.maxAbs()

      Returns the maximum absolute value of the components.


   .. method:: vec4.minAbsIndex()

      Return the index of the component with the minimum absolute value.


   .. method:: vec4.maxAbsIndex()

      Return the index of the component with the maximum absolute value.