finish documenting types

engine/gf_gui.c

@@ -72,11 +72,11 @@ gf_gui_id_t gf_gui_create_button(gf_gui_t* gui, float x, float y, float w, float
 	gf_gui_id_t	    id;
 	gf_gui_component_t* c = gf_gui_first_unused(gui, &id);
 
-	c->type = GF_GUI_BUTTON;
+	c->type	  = GF_GUI_BUTTON;
-	c->x	= x;
+	c->x	  = x;
-	c->y	= y;
+	c->y	  = y;
-	c->w	= w;
+	c->width  = w;
-	c->h	= h;
+	c->height = h;
 
 	c->u.button.pressed = 0;
 	c->u.button.text    = malloc(strlen(text) + 1);
@@ -87,12 +87,16 @@ gf_gui_id_t gf_gui_create_button(gf_gui_t* gui, float x, float y, float w, float
 void gf_gui_render(gf_gui_t* gui) {
 	gf_gui_id_t i;
 	for(i = 0; i < GF_GUI_MAX_COMPONENTS; i++) {
-		gf_gui_component_t* c = &gui->area[i];
+		gf_gui_component_t* c  = &gui->area[i];
+		float		    cx = c->x;
+		float		    cy = c->y;
+		float		    cw = c->width;
+		float		    ch = c->height;
 		switch(c->type) {
 		case GF_GUI_BUTTON: {
-			float x = c->x + c->w / 2 - gf_graphic_text_width(gui->draw, GF_GUI_FONT_SIZE, c->u.button.text) / 2;
+			float x = cx + cw / 2 - gf_graphic_text_width(gui->draw, GF_GUI_FONT_SIZE, c->u.button.text) / 2;
-			float y = c->y + c->h / 2 - GF_GUI_FONT_SIZE / 2;
+			float y = cy + ch / 2 - GF_GUI_FONT_SIZE / 2;
-			gf_gui_draw_box(gui, GF_GUI_NORMAL, c->x, c->y, c->w, c->h);
+			gf_gui_draw_box(gui, GF_GUI_NORMAL, cx, cy, cw, ch);
 			gf_graphic_text(gui->draw, x, y, GF_GUI_FONT_SIZE, c->u.button.text, gf_gui_font_color);
 			break;
 		}

engine/include/gf_draw.h

@@ -31,46 +31,49 @@ GF_EXPORT gf_draw_t* gf_draw_create(gf_engine_t* engine, const char* title);
  * @brief Destroy drawing interface
  * @param draw Drawing interface
  */
-GF_EXPORT void	     gf_draw_destroy(gf_draw_t* draw);
+GF_EXPORT void gf_draw_destroy(gf_draw_t* draw);
 
 /**
  * @~english
  * @brief Draw frame (common part)
  * @param draw Drawing interface
- * @warning Do not call this directly, call gf_draw_step instead
+ * @warning Do not call this - call gf_draw_step instead
  */
-GF_EXPORT void	     gf_draw_frame(gf_draw_t* draw);
+GF_EXPORT void gf_draw_frame(gf_draw_t* draw);
 
 /**
  * @~english
  * @brief Do drawing single step
  * @param draw Drawing interface
  */
-GF_EXPORT int	     gf_draw_step(gf_draw_t* draw);
+GF_EXPORT int gf_draw_step(gf_draw_t* draw);
 
 /**
  * @~english
- * @brief Initialize drawing stuffs, gf_engine_begin calls this
+ * @brief Initialize drawing stuffs
+ * @warning Do not call this - gf_engine_begin calls this
  */
-GF_EXPORT void	     gf_draw_begin(void);
+GF_EXPORT void gf_draw_begin(void);
 
 /**
  * @~english
- * @brief Cleanup drawing stuffs, gf_engine_end calls this
+ * @brief Cleanup drawing stuffs
+ * @warning Do not call this - gf_engine_end calls this
  */
-GF_EXPORT void	     gf_draw_end(void);
+GF_EXPORT void gf_draw_end(void);
 
 /**
  * @~english
- * @brief Set user-drawing callback, called by gf_engine_set_draw
+ * @brief Set user-drawing callback
+ * @warning Do not call this - gf_engine_set_draw calls this
  */
-GF_EXPORT void	     gf_draw_set_draw(gf_draw_t* engine, void (*func)(gf_draw_t*));
+GF_EXPORT void gf_draw_set_draw(gf_draw_t* engine, void (*func)(gf_draw_t*));
 
 /**
  * @~english
  * @brief Do stuffs required on resizing window
  * @note Internal function, you don't need to call this
  */
-GF_EXPORT void	     gf_draw_reshape(gf_draw_t* draw);
+GF_EXPORT void gf_draw_reshape(gf_draw_t* draw);
 
 #endif

engine/include/gf_draw_driver.h

@@ -1,7 +1,7 @@
 /**
- * Renderer driver (e.g. OpenGL)
+ * @file gf_draw_driver.h
- *
+ * @~english
- * Handles driver-specific parts, like lighting.
+ * @brief Drawing driver
  */
 
 #ifndef __GF_DRAW_DRIVER_H__

engine/include/gf_draw_platform.h

@@ -1,7 +1,7 @@
 /**
- * Renderer backend (e.g. GLX)
+ * @file gf_draw_platform.h
- *
+ * @~english
- * Provides the lowest layer for graphics.
+ * @brief Platform-dependent part of drawing driver
  */
 
 #ifndef __GF_DRAW_PLATFORM_H__

engine/include/gf_font.h

@@ -1,5 +1,7 @@
 /**
- * Font
+ * @file gf_font.h
+ * @~english
+ * @brief Font
  */
 
 #ifndef __GF_FONT_H__
@@ -14,6 +16,10 @@
 
 /* Standard */
 
+/**
+ * @~english
+ * @brief Font data
+ */
 GF_EXPORT unsigned char gf_font[128][8];
 
 #endif

engine/include/gf_graphic.h

@@ -1,7 +1,7 @@
 /**
  * @file gf_graphic.h
  * @~english
- * @brief Graphic
+ * @brief Graphic interface
  */
 
 #ifndef __GF_GRAPHIC_H__
@@ -96,18 +96,18 @@ GF_EXPORT float gf_graphic_text_width(gf_draw_t* draw, float size, const char* t
  * @~english
  * @brief Draw text
  */
-GF_EXPORT void	gf_graphic_text(gf_draw_t* draw, float x, float y, float size, const char* text, gf_color_t color);
+GF_EXPORT void gf_graphic_text(gf_draw_t* draw, float x, float y, float size, const char* text, gf_color_t color);
 
 /**
  * @~english
  * @brief Draw filled rectangle
  */
-GF_EXPORT void	gf_graphic_fill_rect(gf_draw_t* draw, float x, float y, float w, float h, gf_color_t color);
+GF_EXPORT void gf_graphic_fill_rect(gf_draw_t* draw, float x, float y, float w, float h, gf_color_t color);
 
 /**
  * @~english
  * @brief Draw rectangle with texture
  */
-GF_EXPORT void	gf_graphic_draw_texture_2d(gf_draw_t* draw, float x, float y, float w, float h, gf_texture_t* texture, gf_color_t color);
+GF_EXPORT void gf_graphic_draw_texture_2d(gf_draw_t* draw, float x, float y, float w, float h, gf_texture_t* texture, gf_color_t color);
 
 #endif

engine/include/gf_gui.h

@@ -1,5 +1,7 @@
 /**
- * GUI
+ * @file gf_gui.h
+ * @~english
+ * @brief GUI
  */
 
 #ifndef __GF_GUI_H__
@@ -16,9 +18,24 @@
 
 /* Standard */
 
+/**
+ * @~english
+ * @brief Draw border normally
+ */
 #define GF_GUI_NORMAL 1
+
+/**
+ * @~english
+ * @brief Draw border inverted
+ */
 #define GF_GUI_INVERT -1
 
+/**
+ * @~english
+ * @brief Create GUI
+ * @param draw Drawing interface
+ * @note You should not have to call this - simply use gf_draw_t::gui
+ */
 GF_EXPORT gf_gui_t*   gf_gui_create(gf_draw_t* draw);
 GF_EXPORT gf_gui_id_t gf_gui_create_button(gf_gui_t* gui, float x, float y, float w, float h, const char* text);
 GF_EXPORT void	      gf_gui_render(gf_gui_t* gui);

engine/include/gf_log.h

@@ -1,8 +1,7 @@
 /**
- * Log
+ * @file gf_log.h
- *
+ * @~english
- * Provides useful function/macro for logging.
+ * @brief Logger
- * Uses the graphical console if possible.
  */
 
 #ifndef __GF_LOG_H__

engine/include/gf_macro.h

@@ -1,5 +1,7 @@
 /**
- * Macro
+ * @file gf_macro.h
+ * @~english
+ * @brief Macro
  */
 
 #ifndef __GF_MACRO_H__
@@ -8,51 +10,119 @@
 #ifdef GF_EXPOSE_ALL
 
 #ifndef GF_EXPOSE_CORE
+/**
+ * @~english
+ * @brief Expose core properties
+ */
 #define GF_EXPOSE_CORE
 #endif
 
 #ifndef GF_EXPOSE_DRAW
+/**
+ * @~english
+ * @brief Expose drawing interface properties
+ */
 #define GF_EXPOSE_DRAW
 #endif
 
 #ifndef GF_EXPOSE_DRAW_PLATFORM
+/**
+ * @~english
+ * @brief Expose platform-dependent part of drawing driver properties
+ */
 #define GF_EXPOSE_DRAW_PLATFORM
 #endif
 
+#ifndef GF_EXPOSE_DRAW_DRIVER
+/**
+ * @~english
+ * @brief Expose drawing driver properties
+ */
+#define GF_EXPOSE_DRAW_DRIVER
+#endif
+
 #ifndef GF_EXPOSE_MESH
+/**
+ * @~english
+ * @brief Expose mesh properties
+ */
 #define GF_EXPOSE_MESH
 #endif
 
 #ifndef GF_EXPOSE_MODEL
+/**
+ * @~english
+ * @brief Expose model properties
+ */
 #define GF_EXPOSE_MODEL
 #endif
 
 #ifndef GF_EXPOSE_TEXTURE
+/**
+ * @~english
+ * @brief Expose texture properties
+ */
 #define GF_EXPOSE_TEXTURE
 #endif
 
 #ifndef GF_EXPOSE_PHYSICS
+/**
+ * @~english
+ * @brief Expose physics interface properties
+ */
 #define GF_EXPOSE_PHYSICS
 #endif
 
+#ifndef GF_EXPOSE_GUI
+/**
+ * @~english
+ * @brief Expose GUI properties
+ */
+#define GF_EXPOSE_GUI
+#endif
+
+#ifndef GF_EXPOSE_THREAD
+/**
+ * @~english
+ * @brief Expose thread interface properties
+ */
+#define GF_EXPOSE_THREAD
+#endif
+
 #ifndef GF_EXPOSE_GRAPHIC
+/**
+ * @~english
+ * @brief Expose graphic interface properties
+ * @note Exposed by default
+ */
 #define GF_EXPOSE_GRAPHIC
 #endif
 
 #ifndef GF_EXPOSE_MATH
+/**
+ * @~english
+ * @brief Expose math properties
+ * @note Exposed by default
+ */
 #define GF_EXPOSE_MATH
 #endif
 
 #ifndef GF_EXPOSE_VERSION
+/**
+ * @~english
+ * @brief Expose version properties
+ * @note Exposed by default
+ */
 #define GF_EXPOSE_VERSION
 #endif
 
-#ifndef GF_EXPOSE_DRAW_DRIVER
-#define GF_EXPOSE_DRAW_DRIVER
-#endif
-
 #endif
 
+/**
+ * @def __FUNCTION_NAME__
+ * @~english
+ * @brief Defined as `__FUNCTION__` on MSVC, otherwise defined as `__func__`
+ */
 #ifndef __FUNCTION_NAME__
 #ifdef _MSC_VER
 #define __FUNCTION_NAME__ __FUNCTION__
@@ -61,6 +131,12 @@
 #endif
 #endif
 
+/**
+ * @~english
+ * @brief Macro to define engine type shorter
+ * @param n Name
+ * @param b Body
+ */
 #define GF_DECLARE_TYPE(n, b) typedef struct gf_##n##_t b gf_##n##_t;
 
 #if defined(_WIN32) && defined(GF_DLL)

engine/include/gf_type/draw.h

@@ -31,10 +31,10 @@ GF_DECLARE_TYPE(draw, );
  * @brief Drawing interface
  *
  * @var gf_draw_t::platform
- * @brief Platform-dependent part of drawing
+ * @brief Platform-dependent part of drawing driver
  *
  * @var gf_draw_t::driver
- * @brief Driver-dependent part of drawing
+ * @brief Drawing driver
  *
  * @var gf_draw_t::gui
  * @brief GUI

engine/include/gf_type/draw_driver.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/draw_driver.h
+ * @~english
+ * @brief Type definitions related to drawing driver
+ */
+
 #ifndef __GF_TYPE_DRAW_DRIVER_H__
 #define __GF_TYPE_DRAW_DRIVER_H__
 
@@ -6,7 +12,7 @@
 
 #ifdef GF_EXPOSE_DRAW_DRIVER
 /* External library */
-#ifdef DRV_OPENGL
+#if defined(DRV_OPENGL)
 #include <gf_opengl.h>
 #endif
 
@@ -14,13 +20,29 @@
 
 /* Standard */
 
-#ifdef DRV_OPENGL
+#if defined(DRV_OPENGL)
 GF_DECLARE_TYPE(draw_driver, { GLUquadric* quadric; });
 GF_DECLARE_TYPE(draw_driver_texture, {
 	GLuint id;
 	int    width;
 	int    height;
 });
+#else
+/**
+ * @struct gf_draw_driver_t
+ * @~english
+ * @brief Drawing driver
+ * @note Definition depends on the drawing driver, read the header file for definition
+ */
+GF_DECLARE_TYPE(draw_driver, {});
+
+/**
+ * @struct gf_draw_driver_texture_t
+ * @~english
+ * @brief Driver-dependent texture
+ * @note Definition depends on the drawing driver, read the header file for definition
+ */
+GF_DECLARE_TYPE(draw_driver_texture, {});
 #endif
 #else
 typedef void gf_draw_driver_t;

engine/include/gf_type/draw_platform.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/draw_platform.h
+ * @~english
+ * @brief Type definitions related to platform-dependent part of drawing driver
+ */
+
 #ifndef __GF_TYPE_DRAW_PLATFORM_H__
 #define __GF_TYPE_DRAW_PLATFORM_H__
 
@@ -6,7 +12,7 @@
 
 #ifdef GF_EXPOSE_DRAW_PLATFORM
 /* External library */
-#ifdef DRV_OPENGL
+#if defined(DRV_OPENGL)
 #include <gf_opengl.h>
 #endif
 
@@ -14,7 +20,7 @@
 
 /* Standard */
 
-#ifdef DRV_OPENGL
+#if defined(DRV_OPENGL)
 #if defined(USE_GLX)
 GF_DECLARE_TYPE(draw_platform, {
 	Display*   display;
@@ -32,6 +38,14 @@ GF_DECLARE_TYPE(draw_platform, {
 #elif defined(USE_GLFW)
 GF_DECLARE_TYPE(draw_platform, { GLFWwindow* window; });
 #endif
+#else
+/**
+ * @struct gf_draw_platform_t
+ * @~english
+ * @brief Platform-dependent part of drawing driver
+ * @note Definition depends on the drawing driver and the platform, read the header file for definition
+ */
+GF_DECLARE_TYPE(draw_platform, {});
 #endif
 #else
 typedef void gf_draw_platform_t;

engine/include/gf_type/gui.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/gui.h
+ * @~english
+ * @brief Type definitions related to GUI
+ */
+
 #ifndef __GF_TYPE_GUI_H__
 #define __GF_TYPE_GUI_H__
 
@@ -14,36 +20,103 @@ typedef int gf_gui_id_t;
 
 /* Standard */
 
+/**
+ * @~english
+ * @brief Max components engine GUI can handle
+ */
 #define GF_GUI_MAX_COMPONENTS 64
 
+/**
+ * @~english
+ * @brief GUI component types
+ */
 enum GF_GUI_COMPONENT_TYPES {
 	GF_GUI_UNUSED = -1,
 	GF_GUI_BUTTON
 };
 
+/**
+ * @struct gf_gui_button_t
+ * @~english
+ * @brief Button component
+ *
+ * @var gf_gui_button_t::text
+ * @brief Button text
+ *
+ * @var gf_gui_button_t::pressed
+ * @brief `1` if pressed, otherwise `0`
+ */
 GF_DECLARE_TYPE(gui_button, {
 	char* text;
 	int   pressed;
 });
 
+/**
+ * @union gf_gui_union_t
+ * @~english
+ * @brief Component union
+ *
+ * @var gf_gui_union_t::button
+ * @brief Button component
+ */
+typedef union gf_gui_union_t {
+	gf_gui_button_t button;
+} gf_gui_union_t;
+
+/**
+ * @struct gf_gui_component_t
+ * @~english
+ * @brief Component
+ *
+ * @var gf_gui_component_t::type
+ * @brief Component type
+ * @see GF_GUI_COMPONENT_TYPES
+ *
+ * @var gf_gui_component_t::x
+ * @brief X coord of component
+ *
+ * @var gf_gui_component_t::y
+ * @brief X coord of component
+ *
+ * @var gf_gui_component_t::width
+ * @brief Width of component
+ *
+ * @var gf_gui_component_t::height
+ * @brief Height of component
+ *
+ * @var gf_gui_component_t::u
+ * @brief Component union
+ */
 GF_DECLARE_TYPE(gui_component, {
-	int   type;
+	int	       type;
-	float x;
+	float	       x;
-	float y;
+	float	       y;
-	float w;
+	float	       width;
-	float h;
+	float	       height;
-	union {
+	gf_gui_union_t u;
-		gf_gui_button_t button;
-	} u;
 });
 
+/**
+ * @struct gf_gui_t
+ * @~english
+ * @brief GUI
+ *
+ * @var gf_gui_t::draw
+ * @brief Drawing interface
+ *
+ * @var gf_gui_t::area
+ * @brief Created components
+ */
 GF_DECLARE_TYPE(gui, {
 	gf_draw_t*	   draw;
 	gf_gui_component_t area[GF_GUI_MAX_COMPONENTS];
 });
 #else
+typedef void gf_gui_button_t;
+
 typedef void gf_gui_t;
 typedef void gf_gui_component_t;
+typedef void gf_gui_union_t;
 #endif
 
 #endif

engine/include/gf_type/math.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/math.h
+ * @~english
+ * @brief Type definitions related to math
+ */
+
 #ifndef __GF_TYPE_MATH_H__
 #define __GF_TYPE_MATH_H__
 
@@ -11,6 +17,11 @@
 
 /* Standard */
 
+/**
+ * @~english
+ * @brief Vector
+ * @note gf_vector_t[3] is used internally
+ */
 typedef double gf_vector_t[4];
 #else
 #error "should not happen!"

engine/include/gf_type/mesh.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/mesh.h
+ * @~english
+ * @brief Type definitions related to mesh
+ */
+
 #ifndef __GF_TYPE_MESH_H__
 #define __GF_TYPE_MESH_H__
 
@@ -12,18 +18,40 @@
 
 /* Standard */
 
-GF_DECLARE_TYPE(shape, {
+/**
+ * @struct gf_triangle_t
+ * @~english
+ * @brief Triangle
+ *
+ * @var gf_triangle_t::points
+ * @brief Triangle points
+ *
+ * @var gf_triangle_t::color
+ * @brief Triangle color
+ */
+GF_DECLARE_TYPE(triangle, {
 	gf_vector_t points[3];
 	gf_vector_t color;
 });
 
+/**
+ * @struct gf_mesh_t
+ * @~english
+ * @brief Mesh
+ *
+ * @var gf_mesh_t::triangles
+ * @brief Triangles
+ *
+ * @var gf_mesh_t::triangle_count
+ * @brief Triangle count
+ */
 GF_DECLARE_TYPE(mesh, {
-	gf_shape_t* shapes;
+	gf_triangle_t* triangles;
-	int	    shape_count;
+	int	       triangle_count;
 });
 #else
 typedef void gf_mesh_t;
-typedef void gf_shape_t;
+typedef void gf_triangle_t;
 #endif
 
 #endif

engine/include/gf_type/model.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/model.h
+ * @~english
+ * @brief Type definitions related to model
+ */
+
 #ifndef __GF_TYPE_MODEL_H__
 #define __GF_TYPE_MODEL_H__
 
@@ -13,6 +19,17 @@
 
 /* Standard */
 
+/**
+ * @struct gf_model_t
+ * @~english
+ * @brief Model
+ *
+ * @var gf_model_t::mesh
+ * @brief Mesh
+ *
+ * @var gf_model_t::texture
+ * @brief Texture
+ */
 GF_DECLARE_TYPE(model, {
 	gf_mesh_t*    mesh;
 	gf_texture_t* texture;

engine/include/gf_type/physics.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/physics.h
+ * @~english
+ * @brief Type definitions related to physics interface
+ */
+
 #ifndef __GF_TYPE_PHYSICS_H__
 #define __GF_TYPE_PHYSICS_H__
 
@@ -12,6 +18,14 @@
 
 /* Standard */
 
+/**
+ * @struct gf_physics_t
+ * @~english
+ * @brief Physics interface
+ *
+ * @var gf_physics_t::id
+ * @brief ODE's world ID
+ */
 GF_DECLARE_TYPE(physics, { dWorldID id; });
 #else
 typedef void gf_physics_t;

engine/include/gf_type/texture.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/texture.h
+ * @~english
+ * @brief Type definitions related to texture
+ */
+
 #ifndef __GF_TYPE_TEXTURE_H__
 #define __GF_TYPE_TEXTURE_H__
 
@@ -12,6 +18,26 @@
 
 /* Standard */
 
+/**
+ * @struct gf_texture_t
+ * @~english
+ * @brief Texture
+ *
+ * @var gf_texture_t::draw_driver_texture
+ * @brief Driver-dependent texture
+ *
+ * @var gf_texture_t::width
+ * @brief Width of texture
+ *
+ * @var gf_texture_t::height
+ * @brief Height of texture
+ *
+ * @var gf_texture_t::internal_width
+ * @brief Internal width of texture
+ *
+ * @var gf_texture_t::internal_height
+ * @brief Internal height of texture
+ */
 GF_DECLARE_TYPE(texture, {
 	gf_draw_driver_texture_t* draw_driver_texture;
 	int			  width;

engine/include/gf_type/thread.h

@@ -1,3 +1,9 @@
+/**
+ * @file gf_type/thread.h
+ * @~english
+ * @brief Type definitions related to thread interface
+ */
+
 #ifndef __GF_TYPE_THREAD_H__
 #define __GF_TYPE_THREAD_H__
 
@@ -16,6 +22,17 @@
 
 /* Standard */
 
+/**
+ * @struct gf_thread_context_t
+ * @~english
+ * @brief Thread context
+ *
+ * @var gf_thread_context_t::func
+ * @brief Function to be called for thread
+ *
+ * @var gf_thread_context_t::data
+ * @brief Data to be passed to thread
+ */
 GF_DECLARE_TYPE(thread_context, {
 	void (*func)(void*);
 	void* data;
@@ -31,6 +48,14 @@ GF_DECLARE_TYPE(thread, {
 	gf_thread_context_t context;
 	HANDLE		    thread;
 });
+#else
+/**
+ * @struct gf_thread_t
+ * @~english
+ * @brief Platform-dependent thread
+ * @note Definition depends on the platform, read the header file for definition
+ */
+GF_DECLARE_TYPE(thread, {});
 #endif
 #else
 typedef void gf_thread_t;