anulax
/
glfw
1
0
Fork 0
Code Issues Pull Requests Packages project_board Releases Wiki Activity

Documentation work.

Browse Source 
Enabled Doxygen tree view, added CMake options for native and internal
modules, improved internal and native documentation.
master
Camilla Berglund ago%!(EXTRA string=12 years)
parent 666181d923
commit 6f8084f061
5 changed files with 117 additions and 92 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 11
      CMakeLists.txt
  2. 19
      docs/Doxyfile.in
  3. 12
      include/GL/glfw3.h
  4. 28
      include/GL/glfw3native.h
  5. 139
      src/internal.h

11
CMakeLists.txt
Unescape 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(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)
option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON)
option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON)

19
docs/Doxyfile.in
Unescape View File

@ -655,7 +655,7 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt
# directories like "/usr/src/myproject". Separate the files or directories
# 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
# 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
# GENERATE_TREEVIEW to YES.
DISABLE_INDEX = NO
DISABLE_INDEX = YES
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
# 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
# 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
# (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
# is shown.
TREEVIEW_WIDTH = 250
TREEVIEW_WIDTH = 300
# 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.
@ -1486,7 +1486,7 @@ EXPAND_ONLY_PREDEF = YES
# 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.
SEARCH_INCLUDES = YES
SEARCH_INCLUDES = NO
# 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
@ -1509,7 +1509,14 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use 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
# this tag can be used to specify a list of macro names that should be expanded.

12
include/GL/glfw3.h
Unescape View File

@ -783,10 +783,12 @@ GLFWAPI void glfwTerminate(void);
*/
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
* enabled when the library was built.
* The format of the string is as follows:
* @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.
* @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
* 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
* GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting. For
* regular windows the initial cursor mode is @c GLFW_CURSOR_NORMAL and the

28
include/GL/glfw3native.h
Unescape View File

@ -39,11 +39,31 @@ extern "C" {
* 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
* to fix problems caused by using it. If you don't, you shouldn't be using
* it.
* <strong>By using the native API, you assert that you know what you are
* doing and how to fix problems caused by using it. If you don't, you
* 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
Unescape View File

@ -79,22 +79,22 @@ typedef struct _GLFWmonitor _GLFWmonitor;
// Doxygen group definitions
//========================================================================
/*! @defgroup platform Platform API
* @brief The API implemented by the platform-specific code.
/*! @defgroup platform Platform interface
* @brief The interface implemented by the platform-specific code.
*
* 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
* the public API except it uses objects instead of handles.
*/
/*! @defgroup event Event API
* @brief The API used by the platform-specific code to report events.
/*! @defgroup event Event interface
* @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
* code of events that can be translated into state changes and/or callback
* calls.
*/
/*! @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
* Each platform may add its own utility functions, but those may only be
@ -325,32 +325,19 @@ int _glfwPlatformInit(void);
*/
void _glfwPlatformTerminate(void);
/*! @brief Returns a string describing the compile-time configuration of the
* platform-specific part of the library.
* @return The version string.
/*! @copydoc glfwGetVersionString
* @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 not change for the duration of the program.
*/
const char* _glfwPlatformGetVersionString(void);
/*! @brief Sets the position of the system cursor.
* @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.
/*! @copydoc glfwSetCursorPos
* @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.
* @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);
/*! @ingroup platform
/*! @copydoc glfwGetMonitors
* @ingroup platform
*/
_GLFWmonitor** _glfwPlatformGetMonitors(int* count);
@ -367,7 +355,8 @@ _GLFWmonitor** _glfwPlatformGetMonitors(int* count);
*/
void _glfwPlatformDestroyMonitor(_GLFWmonitor* monitor);
/*! @ingroup platform
/*! @copydoc glfwGetVideoModes
* @ingroup platform
*/
GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count);
@ -375,33 +364,22 @@ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count);
*/
void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode);
/*! @brief Retrieves the current gamma ramp for the specified monitor.
* @param[in] monitor The monitor to query.
* @param[out] ramp The current system gamma ramp.
/*! @copydoc glfwGetGammaRamp
* @ingroup platform
*/
void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp);
/*! @brief Sets the gamma ramp for the specified monitor.
* @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] ramp The desired system gamma ramp.
/*! @copydoc glfwSetGammaRamp
* @ingroup platform
*/
void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp);
/*! @brief Sets the system clipboard to the specified string.
* @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.
/*! @copydoc glfwSetClipboardString
* @ingroup platform
*/
void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string);
/*! @brief Returns the string in the system clipboard.
* @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.
/*! @copydoc glfwGetClipboardString
* @ingroup platform
*
* @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);
/*! @brief Returns the value of the specified joystick property.
* @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.
/*! @copydoc glfwGetJoystickParam
* @ingroup platform
*/
int _glfwPlatformGetJoystickParam(int joy, int param);
/*! @ingroup platform
/*! @copydoc glfwGetJoystickAxes
* @ingroup platform
*/
int _glfwPlatformGetJoystickAxes(int joy, float* axes, int numaxes);
/*! @ingroup platform
/*! @copydoc glfwGetJoystickButtons
* @ingroup platform
*/
int _glfwPlatformGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons);
/*! @ingroup platform
/*! @copydoc glfwGetJoystickName
* @ingroup platform
*/
const char* _glfwPlatformGetJoystickName(int joy);
/*! @brief Returns the current value of the timer.
* @return The value, in seconds, of the timer.
/*! @copydoc glfwGetTime
* @ingroup platform
*/
double _glfwPlatformGetTime(void);
/*! @brief Sets the value of the timer.
* @param[in] time The new value, in seconds, of the timer.
/*! @copydoc glfwSetTime
* @ingroup platform
*/
void _glfwPlatformSetTime(double time);
@ -451,63 +427,78 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
*/
void _glfwPlatformDestroyWindow(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwSetWindowTitle
* @ingroup platform
*/
void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title);
/*! @ingroup platform
/*! @copydoc glfwGetWindowPos
* @ingroup platform
*/
void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos);
/*! @ingroup platform
/*! @copydoc glfwSetWindowPos
* @ingroup platform
*/
void _glfwPlatformSetWindowPos(_GLFWwindow* window, int xpos, int ypos);
/*! @ingroup platform
/*! @copydoc glfwGetWindowSize
* @ingroup platform
*/
void _glfwPlatformGetWindowSize(_GLFWwindow* window, int* width, int* height);
/*! @ingroup platform
/*! @copydoc glfwSetWindowSize
* @ingroup platform
*/
void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height);
/*! @ingroup platform
/*! @copydoc glfwIconifyWindow
* @ingroup platform
*/
void _glfwPlatformIconifyWindow(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwRestoreWindow
* @ingroup platform
*/
void _glfwPlatformRestoreWindow(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwShowWindow
* @ingroup platform
*/
void _glfwPlatformShowWindow(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwHideWindow
* @ingroup platform
*/
void _glfwPlatformHideWindow(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwPollEvents
* @ingroup platform
*/
void _glfwPlatformPollEvents(void);
/*! @ingroup platform
/*! @copydoc glfwWaitEvents
* @ingroup platform
*/
void _glfwPlatformWaitEvents(void);
/*! @ingroup platform
/*! @copydoc glfwMakeContextCurrent
* @ingroup platform
*/
void _glfwPlatformMakeContextCurrent(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwGetCurrentContext
* @ingroup platform
*/
_GLFWwindow* _glfwPlatformGetCurrentContext(void);
/*! @ingroup platform
/*! @copydoc glfwSwapBuffers
* @ingroup platform
*/
void _glfwPlatformSwapBuffers(_GLFWwindow* window);
/*! @ingroup platform
/*! @copydoc glfwSwapInterval
* @ingroup platform
*/
void _glfwPlatformSwapInterval(int interval);
@ -515,17 +506,7 @@ void _glfwPlatformSwapInterval(int interval);
*/
int _glfwPlatformExtensionSupported(const char* extension);
/*! @ingroup platform
*/
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.
/*! @copydoc glfwGetProcAddress
* @ingroup platform
*/
GLFWglproc _glfwPlatformGetProcAddress(const char* procname);
@ -545,11 +526,11 @@ void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused);
/*! @brief Notifies shared code of a window movement 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] x The new y-coordinate of the client area of the window.
* @param[in] xpos The new x-coordinate of the client area of the window.
* @param[in] ypos The new y-coordinate of the client area of the window.
* @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.
* @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.
* @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.
* @ingroup utility
*/

Write Preview
Loading…
Cancel
Save