diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 73cf39853..2b454b6dc 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -24,3 +24,6 @@ target_link_libraries(quaternion_from_euler ignition-math${IGN_MATH_VER}::igniti add_executable(graph_example graph_example.cc) target_link_libraries(graph_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER}) + +add_executable(color_example color_example.cc) +target_link_libraries(color_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER}) diff --git a/examples/color_example.cc b/examples/color_example.cc new file mode 100644 index 000000000..4d7325a9e --- /dev/null +++ b/examples/color_example.cc @@ -0,0 +1,57 @@ +/* + * Copyright (C) 2021 Open Source Robotics Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * +*/ +//! [complete] +#include +#include + +int main(int argc, char **argv) +{ + +//! [Create a color] + ignition::math::Color a = ignition::math::Color(0.3, 0.4, 0.5); +//! [Create a color] + // The channel order is R, G, B, A and the default alpha value of a should be 1.0 + std::cout << "The alpha value of a should be 1: " << a.A() << std::endl; + + +//! [Set a new color value] + a.ignition::math::Color::Set(0.6, 0.7, 0.8, 1.0); +//! [Set a new color value] + std::cout << "The RGBA value of a: " << a << std::endl; + +//! [Set value from BGRA] + // 0xFF0000FF is blue in BGRA. Convert it to RGBA. + ignition::math::Color::BGRA blue = 0xFF0000FF; + a.ignition::math::Color::SetFromBGRA(blue); +//! [Set value from BGRA] + +//! [Math operator] + std::cout << "Check if a is Blue: " << (a == ignition::math::Color::Blue) << std::endl; + std::cout << "The RGB value of a should be (0, 0, 1): " << a[0] << ", " + << a[1] << ", " + << a[2] << std::endl; +//! [Math operator] + +//! [Set value from HSV] + // Initialize with HSV. (240, 1.0, 1.0) is blue in HSV. + a.ignition::math::Color::SetFromHSV(240.0, 1.0, 1.0); + std::cout << "The HSV value of a: " << a.HSV() << std::endl; + std::cout << "The RGBA value of a should be (0, 0, 1, 1): " << a << std::endl; +//! [Set value from HSV] + +} +//! [complete] diff --git a/include/ignition/math/Color.hh b/include/ignition/math/Color.hh index 2e1d8c1a0..fd6592941 100644 --- a/include/ignition/math/Color.hh +++ b/include/ignition/math/Color.hh @@ -34,6 +34,10 @@ namespace ignition /// \class Color Color.hh ignition/math/Color.hh /// \brief Defines a color using a red (R), green (G), blue (B), and alpha /// (A) component. Each color component is in the range [0..1]. + /// + /// ## Example + /// + /// \snippet examples/color_example.cc complete class IGNITION_MATH_VISIBLE Color { /// \brief (1, 1, 1) @@ -55,18 +59,38 @@ namespace ignition /// \typedef RGBA /// \brief A RGBA packed value as an unsigned int + /// Each 8 bits corresponds to a channel. + /// + /// \code + /// RGBA a = 0xFF0000FF; // (1, 0, 0, 1) for RGBA, i.e. red. + /// \endcode public: typedef unsigned int RGBA; /// \typedef BGRA /// \brief A BGRA packed value as an unsigned int + /// Each 8 bits corresponds to a channel. + /// + /// \code + /// BGRA a = 0xFF0000FF; // (0, 0, 1, 1) for RGBA, i.e. blue. + /// \endcode public: typedef unsigned int BGRA; /// \typedef ARGB /// \brief A ARGB packed value as an unsigned int + /// Each 8 bits corresponds to a channel. + /// + /// \code + /// ARGB a = 0xFF0000FF; // (0, 0, 1, 1) for RGBA, i.e. blue. + /// \endcode public: typedef unsigned int ARGB; /// \typedef ABGR /// \brief A ABGR packed value as an unsigned int + /// Each 8 bits corresponds to a channel. + /// + /// \code + /// ABGR a = 0xFF0000FF; // (1, 0, 0, 1) for RGBA, i.e. red. + /// \endcode public: typedef unsigned int ABGR; /// \brief Constructor diff --git a/tutorials.md.in b/tutorials.md.in index ee951f2ee..31e220980 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -13,6 +13,7 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively. 4. \subpage angle "Angle example" 5. \subpage triangle "Triangle example" 6. \subpage rotation "Rotation example" +7. \subpage color "Color example" ## License diff --git a/tutorials/color.md b/tutorials/color.md new file mode 100644 index 000000000..d051ab287 --- /dev/null +++ b/tutorials/color.md @@ -0,0 +1,58 @@ +\page color Color example + +This tutorial explains how to use the `Color` class from Ignition Math library. + +## Compile the code + +Go to `ign-math/examples` and use `cmake` to compile the code: + +```{.sh} +git clone https://github.com/ignitionrobotics/ign-math/ -b ign-math6 +cd ign-math/examples +mkdir build +cd build +cmake .. +make +``` + +When the code is compiled, run: + +```{.sh} +./color_example +``` + +The ouput of the program: + +```{.sh} +The alpha value of a should be 1: 1 +The RGBA value of a: 0.6 0.7 0.8 1 +Check if a is Blue: 1 +The RGB value of a should be (0, 0, 1): 0, 0, 1 +The HSV value of a: 4 1 1 +The RGBA value of a should be (0, 0, 1, 1): 0 0 1 1 +``` + +## Code + +Create a color with the following RGBA value. The the alpha value is set default to 1.0: + +\snippet examples/color_example.cc Create a color + +Change the value of a color via `Set()`. All values are set default to 1.0 if not specify. + +\snippet examples/color_example.cc Set a new color value + +The ABGR, ARGB, BGRA, RGBA are 4 datatypes that allow you to set color from a 32-bit int. Take BGRA as an example: + +\snippet examples/color_example.cc Set value from BGRA + +Color class overloads math operators including `+`, `-`, `*`, `/`, `[]`, and `==`. + +\snippet examples/color_example.cc Math operator + +You can also set or read a color in HSV. + +\snippet examples/color_example.cc Set value from HSV + +There are more functions in `Color`. Take a look at the [API](https://ignitionrobotics.org/api/math/6.9/classignition_1_1math_1_1Color.html) +