.. oe:namespace:: OESystem


.. meta::
   :keywords: OEColor


.. _OESystem_OEColor:

.. oe:class:: OEColor

   .. oe:api::

      class OEColor

   The :ref:`OEColor <OESystem_OEColor>` class represents colors in terms of
   RGBA (red, green, blue, alpha) components, where alpha is used as an
   opacity channel. Each color component is represented by one byte in the
   range of ``0`` to ``255``. Meaning that
   :math:`2^8*2^8*2^8 = 16,777,216` different colors can be 
   represented.

   The value of alpha is also in the range of ``0`` to ``255``.  If a
   color has an alpha value of ``0``, then the color is fully
   transparent, *i.e.*, invisible. If a color has an alpha value
   ``255``, then the color is fully opaque.

   *OESystem* provides many predefined colors. For example, the color
   black is represented by
   :oe:const:`OEBlack<OESystem::OESystem::OEBlack>` (R=0, G=0, B=0),
   and the color white is represented by
   :oe:const:`OEWhite<OESystem::OESystem::OEWhite>` (R=255, G=255,
   B=255).  The full list of pre-defined colors is shown in 
   :ref:`Figure: List of pre-defined colors<figure_oecolors>`

   .. _figure_oecolors:
   .. figure:: ../images/OEColor.*
      :align: center

      **List of pre-defined colors**

   .. note::

      The alpha for all pre-defined colors is ``255``, entirely
      opaque.

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor()

      .. oe:language:: python

         .. oe:api:: python

            OEColor() -> OEColor

      The default constructor initializes the color object to *white*
      (R=255, B=255, G=255, A=255).

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(const OEColor& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(rhs: OEColor) -> OEColor

      Copy constructor.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(unsigned int packed)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(packed: int) -> OEColor

      Create a color object from a packed 32-bit integer. Each 8-bit
      byte of the integer is assumed to contain a different component
      of the color.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(const std::string& text)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(text: str) -> OEColor

      Create a color object that is initialized with an RGB or an RGBA
      hexadecimal string.  The format of an RGB string is ``#RRGGBB``
      and format of an RGBA string is ``#RRGGBBAA``, where R,G,B and A
      are hexadecimal numbers. For example, the string ``#FF0000``
      represents the color red.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(const unsigned char* rgba)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(rgba: str) -> OEColor

      Create a color object from an array of ``unsigned char``. The
      array is assumed to contain at least 4 bytes, where each byte
      corresponds to RGBA components respectively. 

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(unsigned int red, unsigned int green, unsigned int blue)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(r: int, g: int, b: int) -> OEColor

      Create a color object with a specified `red`, `green`, and
      `blue` color components, the alpha component is set to
      ``255``. Each argument should be in the range of ``0`` to
      ``255``.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor(unsigned int red, unsigned int green, unsigned int blue,
                    unsigned int alpha)

      .. oe:language:: python

         .. oe:api:: python

            OEColor(r: int, g: int, b: int, a: int) -> OEColor

      Create a color object with a specified `red`, `green`, `blue`, and
      `alpha` components.

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEColor & operator=(const OEColor & rhs)

      Assignment operator.


   .. oe:method:: operator!=
      :language: c++

      .. oe:api::

         bool operator!=(const OEColor &rhs) const

      Determines whether two :ref:`OEColor <OESystem_OEColor>` objects are
      different. Two :ref:`OEColor <OESystem_OEColor>` objects are
      considered different, if any of their color components (red,
      green, blue, or alpha) are different.

   .. oe:method:: operator==
      :language: c++

      .. oe:api::

         bool operator==(const OEColor &rhs) const

      Determines whether two :ref:`OEColor <OESystem_OEColor>` objects are
      equal. Two :ref:`OEColor <OESystem_OEColor>` objects are considered
      equivalent if all of their color components (red, green, blue,
      and alpha) are identical.

   .. oe:method:: CreateCopy

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor* CreateCopy() const

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEColor

      Deep copy constructor that returns a pointer to a copy of the
      object.  The memory for the returned :ref:`OEColor <OESystem_OEColor>`
      object is dynamically allocated and owned by the caller.

   .. oe:method:: GetR

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetR() const

      .. oe:language:: python

         .. oe:api:: python

            GetR() -> int

      Returns the red component of the :ref:`OEColor <OESystem_OEColor>`
      object in the range of ``[0, 255]``.

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetR` method


   .. oe:method:: GetG

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetG() const

      .. oe:language:: python

         .. oe:api:: python

            GetG() -> int

      Returns the green component of the :ref:`OEColor <OESystem_OEColor>`
      object in the range of ``[0, 255]``.
 
      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetG` method

         
   .. oe:method:: GetB

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetB() const

      .. oe:language:: python

         .. oe:api:: python

            GetB() -> int

      Returns the blue component of the :ref:`OEColor <OESystem_OEColor>`
      object in the range of ``[0, 255]``.

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetB` method

   .. oe:method:: GetA

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetA() const

      .. oe:language:: python

         .. oe:api:: python

            GetA() -> int

      Returns the alpha component of the :ref:`OEColor <OESystem_OEColor>`
      object in the range of ``[0, 255]``.

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetA` method


   .. oe:method:: GetPackedColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetPackedColor() const

      .. oe:language:: python

         .. oe:api:: python

            GetPackedColor() -> int

      Returns all the components of the :ref:`OEColor <OESystem_OEColor>`
      object packed into a single 32-bit integer. Each 8-bit byte of
      the integer contains a different component of the color.

   .. oe:method:: GetRGBA

      .. oe:language:: c++ java csharp

         .. oe:api::

            const unsigned char* GetRGBA() const

      .. oe:language:: python

         .. oe:api:: python

            GetRGBA() -> str

      Returns all the components of the :ref:`OEColor <OESystem_OEColor>`
      object as an array of 4 bytes.  The array contains 4 bytes,
      where each byte corresponds to RGBA components respectively. The
      pointer returned is owned by the :ref:`OEColor <OESystem_OEColor>`
      object and should not be deallocated by the user. 

   .. oe:method:: GetText

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::string GetText(bool alpha = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetText(a: bool = False) -> str

      Returns the hexadecimal string representation of the
      :ref:`OEColor <OESystem_OEColor>` object. By default the format is
      ``#RRGGBB``. If the ``alpha`` argument is set to ``true`` the
      returned string will include the alpha component in the format
      ``#RRGGBBAA``.

   .. oe:method:: Set

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& Set(unsigned int r, unsigned int g, unsigned int b)
            OEColor& Set(unsigned int r, unsigned int g, unsigned int b,
                         unsigned int a)

      .. oe:language:: python

         .. oe:api:: python

            Set(r: int, g: int, b: int) -> OEColor
            Set(r: int, g: int, b: int, a: int) -> OEColor

      Sets all the components of the :ref:`OEColor <OESystem_OEColor>`
      object. Each argument is assumed to be in the range of ``0`` to
      ``255``. Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.


   .. oe:method:: SetR

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetR(unsigned int r)

      .. oe:language:: python

         .. oe:api:: python

            SetR(r: int) -> OEColor

      Sets the red component of the :ref:`OEColor <OESystem_OEColor>`
      object. 
      The given value is clamped into the range of ``[0, 255]``. 
      Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.

      .. figure:: ../images/OEColorComponentRed.*
         :align: center

         **Examples of changing the red color component**


      .. seealso::

         * :oe:meth:`OESystem::OEColor::GetR` method


   .. oe:method:: SetG

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetG(unsigned int g)

      .. oe:language:: python

         .. oe:api:: python

            SetG(g: int) -> OEColor

      Sets the green component of the :ref:`OEColor <OESystem_OEColor>`
      object. 
      The given value is clamped into the range of ``[0, 255]``. 
      Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.

      .. figure:: ../images/OEColorComponentGreen.*
         :align: center

         **Examples of changing the green color component**

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetG` method


   .. oe:method:: SetB

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetB(unsigned int b)

      .. oe:language:: python

         .. oe:api:: python

            SetB(b: int) -> OEColor

      Sets the blue component of the :ref:`OEColor <OESystem_OEColor>`
      object. 
      The given value is clamped into the range of ``[0, 255]``. 
      Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.

      .. figure:: ../images/OEColorComponentBlue.*
         :align: center

         **Examples of changing the blue color component**

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetB` method


   .. oe:method:: SetA

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetA(unsigned int a)

      .. oe:language:: python

         .. oe:api:: python

            SetA(a: int) -> OEColor

      Sets the alpha component of the :ref:`OEColor <OESystem_OEColor>`
      object. 
      The given value is clamped into the range of ``[0, 255]``. 
      Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.

      .. figure:: ../images/OEColorComponentAlpha.*
         :align: center

         **Examples of changing the alpha (transparency) color component**

      .. seealso::

         * :oe:meth:`OESystem::OEColor::SetA` method


   .. oe:method:: SetPackedColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetPackedColor(unsigned int color)

      .. oe:language:: python

         .. oe:api:: python

            SetPackedColor(color: int) -> OEColor

      Sets all the components of the :ref:`OEColor <OESystem_OEColor>`
      object from a packed 32-bit integer. Each 8-bit
      byte of the integer is assumed to contain a different component
      of the color. Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.

   .. oe:method:: SetRGBA

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetRGBA(const unsigned char* rgba)

      .. oe:language:: python

         .. oe:api:: python

            SetRGBA(rgba: str) -> OEColor

      Sets all the components of the :ref:`OEColor <OESystem_OEColor>` object
      from an array of ``unsigned char``. The array is assumed to
      contain at least 4 bytes, where each byte corresponds to RGBA
      components respectively. Returns a reference to the
      :ref:`OEColor <OESystem_OEColor>` object.


   .. oe:method:: SetText

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor& SetText(const std::string& text)

      .. oe:language:: python

         .. oe:api:: python

            SetText(text: str) -> OEColor

      Sets all the components of the :ref:`OEColor <OESystem_OEColor>` object
      from a RGB or RGBA hexadecimal string. The format of an RGB
      string is ``#RRGGBB`` and format of an RGBA string is
      ``#RRGGBBAA``, where R,G,B and A are hexadecimal numbers. For
      example, the string ``#FF0000`` represents the color
      red. Returns a reference to the :ref:`OEColor <OESystem_OEColor>`
      object.
