mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-10 00:51:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work.

Browse Source 
Enabled Doxygen tree view, added CMake options for native and internal
modules, improved internal and native documentation.
This commit is contained in:
Camilla Berglund 2013-02-14 13:14:17 +01:00
parent 666181d923
commit 6f8084f061
5 changed files with 117 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
CMakeLists.txt
View File

@ -14,6 +14,17 @@ option(GLFW_BUILD_EXAMPLES "Build the GLFW example programs" ON)
option(GLFW_BUILD_TESTS "Build the GLFW test programs" ON) option(GLFW_BUILD_TESTS "Build the GLFW test programs" ON)
option(BUILD_SHARED_LIBS "Build shared libraries" OFF) option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
option(GLFW_DOCUMENT_NATIVE "Include documentation of native access functions" OFF)
option(GLFW_DOCUMENT_INTERNALS "Include documentation of internal functions" OFF)
set(GLFW_DOC_HEADERS "${GLFW_SOURCE_DIR}/include/GL/glfw3.h")
if (GLFW_DOCUMENT_NATIVE)
set(GLFW_DOC_HEADERS "${GLFW_DOC_HEADERS} ${GLFW_SOURCE_DIR}/include/GL/glfw3native.h")
endif()
if (GLFW_DOCUMENT_INTERNALS)
set(GLFW_DOC_HEADERS "${GLFW_DOC_HEADERS} ${GLFW_SOURCE_DIR}/src/internal.h")
endif()
if (APPLE) if (APPLE)
option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON) option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON)
option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON) option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON)

19
docs/Doxyfile.in
View File

@ -655,7 +655,7 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt
# directories like "/usr/src/myproject". Separate the files or directories # directories like "/usr/src/myproject". Separate the files or directories
# with spaces. # with spaces.
INPUT = @GLFW_SOURCE_DIR@/include/GL/glfw3.h INPUT = @GLFW_DOC_HEADERS@
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@ -1115,7 +1115,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project
# navigation tree you can set this option to NO if you already set # navigation tree you can set this option to NO if you already set
# GENERATE_TREEVIEW to YES. # GENERATE_TREEVIEW to YES.
DISABLE_INDEX = NO DISABLE_INDEX = YES
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
# structure should be generated to display hierarchical information. # structure should be generated to display hierarchical information.
@ -1127,7 +1127,7 @@ DISABLE_INDEX = NO
# Since the tree basically has the same information as the tab index you # Since the tree basically has the same information as the tab index you
# could consider to set DISABLE_INDEX to NO when enabling this option. # could consider to set DISABLE_INDEX to NO when enabling this option.
GENERATE_TREEVIEW = NO GENERATE_TREEVIEW = YES
# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values
# (range [0,1..20]) that doxygen will group on one line in the generated HTML # (range [0,1..20]) that doxygen will group on one line in the generated HTML
@ -1140,7 +1140,7 @@ ENUM_VALUES_PER_LINE = 4
# used to set the initial width (in pixels) of the frame in which the tree # used to set the initial width (in pixels) of the frame in which the tree
# is shown. # is shown.
TREEVIEW_WIDTH = 250 TREEVIEW_WIDTH = 300
# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open # When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open
# links to external symbols imported via tag files in a separate window. # links to external symbols imported via tag files in a separate window.
@ -1486,7 +1486,7 @@ EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# pointed to by INCLUDE_PATH will be searched when a #include is found. # pointed to by INCLUDE_PATH will be searched when a #include is found.
SEARCH_INCLUDES = YES SEARCH_INCLUDES = NO
# The INCLUDE_PATH tag can be used to specify one or more directories that # The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by # contain include files that are not input files but should be processed by
@ -1509,7 +1509,14 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator # undefined via #undef or recursively expanded use the := operator
# instead of the = operator. # instead of the = operator.
PREDEFINED = GLFWAPI= PREDEFINED = GLFWAPI= \
GLFW_EXPOSE_NATIVE_WIN32 \
GLFW_EXPOSE_NATIVE_WGL \
GLFW_EXPOSE_NATIVE_X11 \
GLFW_EXPOSE_NATIVE_GLX \
GLFW_EXPOSE_NATIVE_COCOA \
GLFW_EXPOSE_NATIVE_NSGL \
GLFW_EXPOSE_NATIVE_EGL
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded. # this tag can be used to specify a list of macro names that should be expanded.

12
include/GL/glfw3.h
View File

@ -783,10 +783,12 @@ GLFWAPI void glfwTerminate(void);
*/ */
GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
/*! @brief Returns the version string of the GLFW library. /*! @brief Returns a string describing the compile-time configuration.
* *
* The version string contains information about what compile-time options were * The format of the string is as follows:
* enabled when the library was built. * @arg The name of the window system API
* @arg The name of the context creation API
* @arg Any additional options or APIs
* *
* @return The GLFW version string. * @return The GLFW version string.
* @ingroup init * @ingroup init
@ -1062,6 +1064,10 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* can use the newly created context, you need to make it current using @ref * can use the newly created context, you need to make it current using @ref
* glfwMakeContextCurrent. * glfwMakeContextCurrent.
* *
* @remarks To create the window at a specific position, make it initially
* invisible using the @c GLFW_VISIBLE window hint, set its position and then
* show it.
*
* @remarks For fullscreen windows the initial cursor mode is @c * @remarks For fullscreen windows the initial cursor mode is @c
* GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting. For * GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting. For
* regular windows the initial cursor mode is @c GLFW_CURSOR_NORMAL and the * regular windows the initial cursor mode is @c GLFW_CURSOR_NORMAL and the

28
include/GL/glfw3native.h
View File

@ -39,11 +39,31 @@ extern "C" {
* Doxygen documentation * Doxygen documentation
*************************************************************************/ *************************************************************************/
/*! @defgroup native Native API /*! @defgroup native Native access
* *
* By using the native API, you assert that you know what you are doing and how * <strong>By using the native API, you assert that you know what you are
* to fix problems caused by using it. If you don't, you shouldn't be using * doing and how to fix problems caused by using it. If you don't, you
* it. * shouldn't be using it.</strong>
*
* Before the inclusion of @ref glfw3native.h, you must define exactly one
* window API macro and exactly one context API macro. Failure to do this
* will cause a compile-time error.
*
* The available window API macros are:
* @arg @c GLFW_EXPOSE_NATIVE_WIN32
* @arg @c GLFW_EXPOSE_NATIVE_COCOA
* @arg @c GLFW_EXPOSE_NATIVE_X11
*
* The available context API macros are:
* @arg @c GLFW_EXPOSE_NATIVE_WGL
* @arg @c GLFW_EXPOSE_NATIVE_NSGL
* @arg @c GLFW_EXPOSE_NATIVE_GLX
* @arg @c GLFW_EXPOSE_NATIVE_EGL
*
* These macros select which of the native access functions are declared and
* which platform-specific headers to include. It is then up your (by
* definition platform-specific) code to handle which of these should be
* defined.
*/ */

139
src/internal.h
View File

@ -79,22 +79,22 @@ typedef struct _GLFWmonitor _GLFWmonitor;
// Doxygen group definitions // Doxygen group definitions
//======================================================================== //========================================================================
/*! @defgroup platform Platform API /*! @defgroup platform Platform interface
* @brief The API implemented by the platform-specific code. * @brief The interface implemented by the platform-specific code.
* *
* The platform API is the interface exposed by the platform-specific code for * The platform API is the interface exposed by the platform-specific code for
* each platform and is called by the shared code of the public API It mirrors * each platform and is called by the shared code of the public API It mirrors
* the public API except it uses objects instead of handles. * the public API except it uses objects instead of handles.
*/ */
/*! @defgroup event Event API /*! @defgroup event Event interface
* @brief The API used by the platform-specific code to report events. * @brief The interface used by the platform-specific code to report events.
* *
* The event API is used by the platform-specific code to notify the shared * The event API is used by the platform-specific code to notify the shared
* code of events that can be translated into state changes and/or callback * code of events that can be translated into state changes and/or callback
* calls. * calls.
*/ */
/*! @defgroup utility Utility functions /*! @defgroup utility Utility functions
* @brief Various utility functions. * @brief Various utility functions for internal use.
* *
* These functions are shared code and may be used by any part of GLFW * These functions are shared code and may be used by any part of GLFW
* Each platform may add its own utility functions, but those may only be * Each platform may add its own utility functions, but those may only be
@ -325,32 +325,19 @@ int _glfwPlatformInit(void);
*/ */
void _glfwPlatformTerminate(void); void _glfwPlatformTerminate(void);
/*! @brief Returns a string describing the compile-time configuration of the /*! @copydoc glfwGetVersionString
* platform-specific part of the library.
* @return The version string.
* @ingroup platform * @ingroup platform
* *
* The format of the string is as follows:
* @arg The name of the window system API used
* @arg The name of the context creation API used
* @arg Any additional options or APIs
*
* @note The returned string must be available for the duration of the program. * @note The returned string must be available for the duration of the program.
* *
* @note The returned string must not change for the duration of the program. * @note The returned string must not change for the duration of the program.
*/ */
const char* _glfwPlatformGetVersionString(void); const char* _glfwPlatformGetVersionString(void);
/*! @brief Sets the position of the system cursor. /*! @copydoc glfwSetCursorPos
* @param[in] window The window whose client area the specified posiiton is
* relative to.
* @param[in] x The new x-coordinate of the cursor, relative to the left edge
* of the client area of the window.
* @param[in] y The new y-coordinate of the cursor, relative to the top edge
* of the client area of the window.
* @ingroup platform * @ingroup platform
*/ */
void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y); void _glfwPlatformSetCursorPos(_GLFWwindow* window, int xpos, int ypos);
/*! @brief Sets up the specified cursor mode for the specified window. /*! @brief Sets up the specified cursor mode for the specified window.
* @param[in] window The window whose cursor mode to change. * @param[in] window The window whose cursor mode to change.
@ -359,7 +346,8 @@ void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y);
*/ */
void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode); void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode);
/*! @ingroup platform /*! @copydoc glfwGetMonitors
* @ingroup platform
*/ */
_GLFWmonitor** _glfwPlatformGetMonitors(int* count); _GLFWmonitor** _glfwPlatformGetMonitors(int* count);
@ -367,7 +355,8 @@ _GLFWmonitor** _glfwPlatformGetMonitors(int* count);
*/ */
void _glfwPlatformDestroyMonitor(_GLFWmonitor* monitor); void _glfwPlatformDestroyMonitor(_GLFWmonitor* monitor);
/*! @ingroup platform /*! @copydoc glfwGetVideoModes
* @ingroup platform
*/ */
GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count); GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count);
@ -375,33 +364,22 @@ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count);
*/ */
void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode); void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode);
/*! @brief Retrieves the current gamma ramp for the specified monitor. /*! @copydoc glfwGetGammaRamp
* @param[in] monitor The monitor to query.
* @param[out] ramp The current system gamma ramp.
* @ingroup platform * @ingroup platform
*/ */
void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp); void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp);
/*! @brief Sets the gamma ramp for the specified monitor. /*! @copydoc glfwSetGammaRamp
* @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] ramp The desired system gamma ramp.
* @ingroup platform * @ingroup platform
*/ */
void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp); void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp);
/*! @brief Sets the system clipboard to the specified string. /*! @copydoc glfwSetClipboardString
* @param[in] window The window who will own the system clipboard contents, on
* systems where this is necessary.
* @param[in] string The UTF-8 encoded string to use.
* @ingroup platform * @ingroup platform
*/ */
void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string); void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string);
/*! @brief Returns the string in the system clipboard. /*! @copydoc glfwGetClipboardString
* @param[in] window The window who will request the system clipboard contents,
* on systems where this is necessary.
* @return The UTF-8 encoded contents, or @c NULL if the system clipboard did
* not contain a string.
* @ingroup platform * @ingroup platform
* *
* @note The returned string must be valid until the next call to @ref * @note The returned string must be valid until the next call to @ref
@ -409,34 +387,32 @@ void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string);
*/ */
const char* _glfwPlatformGetClipboardString(_GLFWwindow* window); const char* _glfwPlatformGetClipboardString(_GLFWwindow* window);
/*! @brief Returns the value of the specified joystick property. /*! @copydoc glfwGetJoystickParam
* @param[in] joy The joystick to use.
* @param[in] param The property whose value to return.
* @return The value of the specified property, or zero if an error occurred.
* @ingroup platform * @ingroup platform
*/ */
int _glfwPlatformGetJoystickParam(int joy, int param); int _glfwPlatformGetJoystickParam(int joy, int param);
/*! @ingroup platform /*! @copydoc glfwGetJoystickAxes
* @ingroup platform
*/ */
int _glfwPlatformGetJoystickAxes(int joy, float* axes, int numaxes); int _glfwPlatformGetJoystickAxes(int joy, float* axes, int numaxes);
/*! @ingroup platform /*! @copydoc glfwGetJoystickButtons
* @ingroup platform
*/ */
int _glfwPlatformGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons); int _glfwPlatformGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons);
/*! @ingroup platform /*! @copydoc glfwGetJoystickName
* @ingroup platform
*/ */
const char* _glfwPlatformGetJoystickName(int joy); const char* _glfwPlatformGetJoystickName(int joy);
/*! @brief Returns the current value of the timer. /*! @copydoc glfwGetTime
* @return The value, in seconds, of the timer.
* @ingroup platform * @ingroup platform
*/ */
double _glfwPlatformGetTime(void); double _glfwPlatformGetTime(void);
/*! @brief Sets the value of the timer. /*! @copydoc glfwSetTime
* @param[in] time The new value, in seconds, of the timer.
* @ingroup platform * @ingroup platform
*/ */
void _glfwPlatformSetTime(double time); void _glfwPlatformSetTime(double time);
@ -451,63 +427,78 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
*/ */
void _glfwPlatformDestroyWindow(_GLFWwindow* window); void _glfwPlatformDestroyWindow(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwSetWindowTitle
* @ingroup platform
*/ */
void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title); void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title);
/*! @ingroup platform /*! @copydoc glfwGetWindowPos
* @ingroup platform
*/ */
void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos); void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos);
/*! @ingroup platform /*! @copydoc glfwSetWindowPos
* @ingroup platform
*/ */
void _glfwPlatformSetWindowPos(_GLFWwindow* window, int xpos, int ypos); void _glfwPlatformSetWindowPos(_GLFWwindow* window, int xpos, int ypos);
/*! @ingroup platform /*! @copydoc glfwGetWindowSize
* @ingroup platform
*/ */
void _glfwPlatformGetWindowSize(_GLFWwindow* window, int* width, int* height); void _glfwPlatformGetWindowSize(_GLFWwindow* window, int* width, int* height);
/*! @ingroup platform /*! @copydoc glfwSetWindowSize
* @ingroup platform
*/ */
void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height); void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height);
/*! @ingroup platform /*! @copydoc glfwIconifyWindow
* @ingroup platform
*/ */
void _glfwPlatformIconifyWindow(_GLFWwindow* window); void _glfwPlatformIconifyWindow(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwRestoreWindow
* @ingroup platform
*/ */
void _glfwPlatformRestoreWindow(_GLFWwindow* window); void _glfwPlatformRestoreWindow(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwShowWindow
* @ingroup platform
*/ */
void _glfwPlatformShowWindow(_GLFWwindow* window); void _glfwPlatformShowWindow(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwHideWindow
* @ingroup platform
*/ */
void _glfwPlatformHideWindow(_GLFWwindow* window); void _glfwPlatformHideWindow(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwPollEvents
* @ingroup platform
*/ */
void _glfwPlatformPollEvents(void); void _glfwPlatformPollEvents(void);
/*! @ingroup platform /*! @copydoc glfwWaitEvents
* @ingroup platform
*/ */
void _glfwPlatformWaitEvents(void); void _glfwPlatformWaitEvents(void);
/*! @ingroup platform /*! @copydoc glfwMakeContextCurrent
* @ingroup platform
*/ */
void _glfwPlatformMakeContextCurrent(_GLFWwindow* window); void _glfwPlatformMakeContextCurrent(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwGetCurrentContext
* @ingroup platform
*/ */
_GLFWwindow* _glfwPlatformGetCurrentContext(void); _GLFWwindow* _glfwPlatformGetCurrentContext(void);
/*! @ingroup platform /*! @copydoc glfwSwapBuffers
* @ingroup platform
*/ */
void _glfwPlatformSwapBuffers(_GLFWwindow* window); void _glfwPlatformSwapBuffers(_GLFWwindow* window);
/*! @ingroup platform /*! @copydoc glfwSwapInterval
* @ingroup platform
*/ */
void _glfwPlatformSwapInterval(int interval); void _glfwPlatformSwapInterval(int interval);
@ -515,17 +506,7 @@ void _glfwPlatformSwapInterval(int interval);
*/ */
int _glfwPlatformExtensionSupported(const char* extension); int _glfwPlatformExtensionSupported(const char* extension);
/*! @ingroup platform /*! @copydoc glfwGetProcAddress
*/
GLFWglproc _glfwPlatformGetProcAddress(const char* procname);
/*! @ingroup platform
*/
int _glfwPlatformExtensionSupported(const char* extension);
/*! @brief Returns the address of the specified client API function.
* @param[in] procname The name of the desired function.
* @return The address of the function, or @c NULL if it is not available.
* @ingroup platform * @ingroup platform
*/ */
GLFWglproc _glfwPlatformGetProcAddress(const char* procname); GLFWglproc _glfwPlatformGetProcAddress(const char* procname);
@ -545,11 +526,11 @@ void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused);
/*! @brief Notifies shared code of a window movement event. /*! @brief Notifies shared code of a window movement event.
* @param[in] window The window that received the event. * @param[in] window The window that received the event.
* @param[in] x The new x-coordinate of the client area of the window. * @param[in] xpos The new x-coordinate of the client area of the window.
* @param[in] x The new y-coordinate of the client area of the window. * @param[in] ypos The new y-coordinate of the client area of the window.
* @ingroup event * @ingroup event
*/ */
void _glfwInputWindowPos(_GLFWwindow* window, int x, int y); void _glfwInputWindowPos(_GLFWwindow* window, int xpos, int ypos);
/*! @brief Notifies shared code of a window resize event. /*! @brief Notifies shared code of a window resize event.
* @param[in] window The window that received the event. * @param[in] window The window that received the event.
@ -669,7 +650,7 @@ void _glfwSplitBPP(int bpp, int* red, int* green, int* blue);
/*! @brief Searches an extension string for the specified extension. /*! @brief Searches an extension string for the specified extension.
* @param[in] string The extension string to search. * @param[in] string The extension string to search.
* @param[in] extension The extension to search for. * @param[in] extensions The extension to search for.
* @return @c GL_TRUE if the extension was found, or @c GL_FALSE otherwise. * @return @c GL_TRUE if the extension was found, or @c GL_FALSE otherwise.
* @ingroup utility * @ingroup utility
*/ */