[Misc] Renamed Throw.h to Trap.h and made Trap() publicly available.

This builds upon the new way to better handle exceptions in the public interface (671c74e).
Instead of only calling abort() when exceptions are disabled, this change makes use of the
already implemented Trap() function that provides a full callstack and other functionality.
Since LLGL does not handle but only throws exceptions, we accept that this only provides a
handful of predefined exceptions for the few cases they are used in the public header files.

include/LLGL/Trap.h

@@ -0,0 +1,73 @@
+/*
+ * Trap.h
+ *
+ * Copyright (c) 2015 Lukas Hermanns. All rights reserved.
+ * Licensed under the terms of the BSD 3-Clause license (see LICENSE.txt).
+ */
+
+#ifndef LLGL_TRAP_H
+#define LLGL_TRAP_H
+
+
+#include <LLGL/Export.h>
+
+
+/**
+\brief Helper macro to trap execution when the condition fails.
+\remarks LLGL only throws exceptions if it was built with \c LLGL_ENABLE_EXCEPTIONS.
+\see LLGL::Trap
+*/
+#define LLGL_VERIFY(CONDITION, EXCEPTION)                                                           \
+    if (!(CONDITION))                                                                               \
+    {                                                                                               \
+        LLGL::Trap(LLGL::Exception::EXCEPTION, __FUNCTION__, "assertion failed: %s", #CONDITION);   \
+    }
+
+
+namespace LLGL
+{
+
+
+/**
+\brief Enumeration of all exception classes Trap() can throw.
+\remarks LLGL only throws exceptions if it was built with \c LLGL_ENABLE_EXCEPTIONS.
+\see Trap
+*/
+enum class Exception
+{
+    //! Refers to std::runtime_error.
+    RuntimeError,
+
+    //! Refers to std::out_of_range.
+    OutOfRange,
+
+    //! Refers to std::bad_cast.
+    BadCast,
+
+    //! Refers to std::invalid_argument.
+    InvalidArgument,
+};
+
+
+/**
+\brief Primary function to trap execution from an unrecoverable state.
+\param[in] exception Specifies what type of exception this function should throw if exceptions are enabled.
+\param[in] origin Specifies the origin where execution is trapped. This can be the special preprocessor macro \c __FUNCTION__ for instance.
+\param[in] format Specifies the formatted string as used with \c printf.
+\remarks This might either throw an exception, abort execution, or break the debugger depending on the configuration LLGL was built with.
+LLGL does not handle exceptions of any kind but can throw exceptions (if built with \c LLGL_ENABLE_EXCEPTIONS)
+to let the client programmer exit the application gracefully.
+Otherwise, this function simply aborts execution and dumps the callstack to the standard error pipe.
+*/
+[[noreturn]]
+LLGL_EXPORT void Trap(Exception exception, const char* origin, const char* format, ...);
+
+
+} // /namespace LLGL
+
+
+#endif
+
+
+
+// ================================================================================

include/LLGL/TypeInfo.h

@@ -10,7 +10,7 @@
 
 
 #include <LLGL/Interface.h>
-#include <LLGL/Throw.h>
+#include <LLGL/Trap.h>
 
 
 namespace LLGL
@@ -98,8 +98,7 @@ const LLGL::Window& myWindow = LLGL::CastTo<LLGL::Window>(mySurface);
 template <typename T>
 inline const T& CastTo(const Interface& obj)
 {
-    LLGL_VERIFY_OR_THROW(IsInstanceOf<T>(obj), std::bad_cast());
-
+    LLGL_VERIFY(IsInstanceOf<T>(obj), BadCast);
     return static_cast<const T&>(obj);
 }
 
@@ -118,8 +117,7 @@ LLGL::Window& myWindow = LLGL::CastTo<LLGL::Window&>(mySurface);
 template <typename T>
 inline T& CastTo(Interface& obj)
 {
-    LLGL_VERIFY_OR_THROW(IsInstanceOf<T>(obj), std::bad_cast());
-
+    LLGL_VERIFY(IsInstanceOf<T>(obj), BadCast);
     return static_cast<T&>(obj);
 }
 

include/LLGL/Utils/Color.h

@@ -9,9 +9,9 @@
 #define LLGL_COLOR_H
 
 
-#include <LLGL/Throw.h>
 #include <LLGL/Export.h>
 #include <LLGL/Tags.h>
+#include <LLGL/Trap.h>
 #include <algorithm>
 #include <type_traits>
 #include <cstdint>
@@ -201,8 +201,7 @@ class LLGL_EXPORT Color
         */
         T& operator [] (std::size_t component)
         {
-            LLGL_VERIFY_OR_THROW(component < N, std::out_of_range("color component index out of range"));
-
+            LLGL_VERIFY(component < N, OutOfRange);
             return v_[component];
         }
 
@@ -213,8 +212,7 @@ class LLGL_EXPORT Color
         */
         const T& operator [] (std::size_t component) const
         {
-            LLGL_VERIFY_OR_THROW(component < N, std::out_of_range("color component index out of range"));
-
+            LLGL_VERIFY(component < N, OutOfRange);
             return v_[component];
         }
 

include/LLGL/Utils/ColorRGB.h

@@ -10,7 +10,7 @@
 
 
 #include <LLGL/Utils/Color.h>
-#include <LLGL/Throw.h>
+#include <LLGL/Trap.h>
 
 
 namespace LLGL
@@ -144,8 +144,7 @@ class LLGL_EXPORT Color<T, 3u>
         */
         T& operator [] (std::size_t component)
         {   
-            LLGL_VERIFY_OR_THROW((component < Color<T, 3>::components), std::out_of_range("color component index out of range (must be 0, 1, or 2)"));
-
+            LLGL_VERIFY((component < Color<T, 3>::components), OutOfRange);
             return *((&r) + component);
         }
 
@@ -156,8 +155,7 @@ class LLGL_EXPORT Color<T, 3u>
         */
         const T& operator [] (std::size_t component) const
         {
-            LLGL_VERIFY_OR_THROW((component < Color<T, 3>::components), std::out_of_range("color component index out of range (must be 0, 1, or 2)"));
-
+            LLGL_VERIFY((component < Color<T, 3>::components), OutOfRange);
             return *((&r) + component);
         }
 

include/LLGL/Utils/ColorRGBA.h

@@ -9,8 +9,8 @@
 #define LLGL_COLOR_RGBA_H
 
 
-#include <LLGL/Throw.h>
 #include <LLGL/Utils/Color.h>
+#include <LLGL/Trap.h>
 
 
 namespace LLGL
@@ -180,8 +180,7 @@ class LLGL_EXPORT Color<T, 4u>
         */
         T& operator [] (std::size_t component)
         {
-            LLGL_VERIFY_OR_THROW((component < Color<T, 4>::components), std::out_of_range("color component index out of range (must be 0, 1, 2, or 3)"));
-
+            LLGL_VERIFY((component < Color<T, 4>::components), OutOfRange);
             return *((&r) + component);
         }
 
@@ -192,8 +191,7 @@ class LLGL_EXPORT Color<T, 4u>
         */
         const T& operator [] (std::size_t component) const
         {
-            LLGL_VERIFY_OR_THROW((component < Color<T, 4>::components), std::out_of_range("color component index out of range (must be 0, 1, 2, or 3)"));
-
+            LLGL_VERIFY((component < Color<T, 4>::components), OutOfRange);
             return *((&r) + component);
         }