fix debug environment labels

- front and back labels where inverted:
  +z is the front of the cube and -z is its back
  when looking at the cube from the outside
  with a camera pointing towards -z (and the cube
  in front of it). This is the GL definition.

- make the synthetic uvXXX debug environment 
  colors match those of the debug environment
  (except for -Z/back which is magenta instead
  of black).

- add some documentation about skybox and cube map.

filament/include/filament/Skybox.h

@@ -79,6 +79,13 @@ class UTILS_PUBLIC Skybox : public FilamentAPI {
         /**
          * Set the environment map (i.e. the skybox content).
          *
+         * The Skybox is rendered as though it were an infinitely large cube with the camera
+         * inside it. This means that the cubemap which is mapped onto the cube's exterior
+         * will appear mirrored. This follows the OpenGL conventions.
+         *
+         * The cmgen tool generates reflection maps by default which are therefore ideal to use
+         * as skyboxes.
+         *
          * @param cubemap This Texture must be a cube map.
          *
          * @return This Builder, for chaining calls.

filament/include/filament/Texture.h

@@ -279,6 +279,8 @@ class UTILS_PUBLIC Texture : public FilamentAPI {
     /**
      * Specify all six images of a cube map level.
      *
+     * This method follows exactly the OpenGL conventions.
+     *
      * @param engine        Engine this texture is associated to.
      * @param level         Level to set the image for.
      * @param buffer        Client-side buffer containing the images to set.

tools/cmgen/src/CubemapUtils.cpp

@@ -201,12 +201,12 @@ void CubemapUtils::mirrorCubemap(Cubemap& dst, const Cubemap& src) {
 
 void CubemapUtils::generateUVGrid(Cubemap& cml, size_t gridFrequency) {
     Cubemap::Texel const colors[6] = {
-            { 1, 0, 0 }, // l
-            { 0, 1, 1 }, // r
-            { 0, 1, 0 }, // b
-            { 1, 0, 1 }, // t
-            { 0, 0, 1 }, // bk
-            { 1, 1, 0 }, // fr
+            { 1, 0, 0 }, // -X /  l  - red
+            { 1, 1, 1 }, // +X /  r  - white
+            { 0, 1, 0 }, // -Y /  b  - green
+            { 0, 0, 1 }, // +Y /  t  - blue
+            { 1, 0, 1 }, // -Z / bk - magenta
+            { 1, 1, 0 }, // +z / fr - yellow
     };
     const float uvGridHDRIntensity = 5.0f;
     size_t gridSize = cml.getDimensions() / gridFrequency;