Commits

Jason McKesson  committed 5803194

Docs: Section on header inclusion.

  • Participants
  • Parent commits 503b20c

Comments (0)

Files changed (5)

File docs/glsdk.doxy

 
 Bugs or feature requests should be filed in the <a href="https://bitbucket.org/alfonse/unofficial-opengl-sdk/issues?status=new&status=open">Bitbucket issue tracker</a> for the SDK. However, bugs can also be filed on the SourceForge issue tracker. Questions or other inquiries can be directed to the <a href="http://www.opengl.org/discussion_boards/">OpenGL forums</a>.
 
-\section mainpage_notation Notation
+@ref You can look on the \ref module_troubleshooting "troubleshooting page" for information about combating common problems.
+
+\section mainpage_notation Request for Aid
 
 The Unofficial GL SDK is still in Alpha at present. Currently, the SDK is missing the following libraries:
 

File docs/modules.doxy

 
 **/
 
+/**
+\defgroup module_troubleshooting Troubleshooting
+
+@section trouble_headers Header Inclusion Order
+
+Headers must be included in certain orders. GLFW and FreeGLUT headers must be included \em after including one of the GL Load OpenGL headers. For example, if you want to use OpenGL 3.3 core with FreeGLUT, you must include them in this order:
+
+\code
+#include <glload/gl_3_3.h>
+#include <GL/freeglut.h>
+\endcode
+
+This is because FreeGLUT requires some of the types defined in the GL Load headers. Normally, it would include <tt>GL/gl.h</tt> directly, but since GL Load cannot work with the old header, we have to forcibly include it outselves first.
+
+The same goes for GLEW.
+
+The GLimg library headers <em>do not</em> require the inclusion of any GL Load headers. Some of the Texture Generation functions return <tt>unsigned int</tt> instead of actual GLenum values in order to support this.
+
+GL Util and GL Mesh headers can require GL Load inclusion on a case-by-case basis. Each file that requires it will have a notation in the documentation for that particular header file. Thus, if you include glutil.h or glmesh.h, you \em need to include a GL Load header first.
+
+A good rule of thumb is to simply include the GL Load headers before including \em anything else from the SDK.
+**/
+

File glimg/include/glimg/TextureGenerator.h

 	\param pImage The image that would be uploaded in a CreateTexture call.
 	\param forceConvertBits A bitfield containing values from ForcedConvertFlags.
 
-	\return The texture type for a texture that would be created with CreateTexture.
+	\return A GLenum for the texture type for a texture that would be created by CreateTexture.
 	**/
-	GLenum GetTextureType(const ImageSet *pImage, unsigned int forceConvertBits);
+	unsigned int GetTextureType(const ImageSet *pImage, unsigned int forceConvertBits);
 
 	/**
 	\brief Creates a texture object from the given ImageSet, with flags.

File glimg/source/TextureGenerator.cpp

 		}
 	}
 
-	GLenum GetTextureType( const ImageSet *pImage, unsigned int forceConvertBits )
+	unsigned int GetTextureType( const ImageSet *pImage, unsigned int forceConvertBits )
 	{
 		Dimensions dims = pImage->GetDimensions();
 
 			return gl::GL_TEXTURE_3D;
 		}
 
-		return -1;
+		return 0xFFFFFFFF;
 	}
 
 	unsigned int CreateTexture( const ImageSet *pImage, unsigned int forceConvertBits )

File glload/glload.doxy

 }
 \endcode
 
+\note The inclusion order of headers can be a common compilation issue. See \ref trouble_headers "this section" to know when you need to include a GL Load header before another header in the SDK.
 **/
 
 /**