add color example

Signed-off-by: youhy <[email protected]>

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})

examples/color_example.cc

@@ -0,0 +1,51 @@
+/*
+ * Copyright (C) 2019 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 <iostream>
+#include <ignition/math/Color.hh>
+
+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]
+  std::cout << "Check if a is Blue: " << (a == ignition::math::Color::Blue) << std::endl;
+
+//! [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);
+//! [Set value from HSV]
+  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;
+
+}
+//! [complete]

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