Commit bb3ab87a authored by Camilla Löwy's avatar Camilla Löwy
Browse files

Remove unmaintained internal Doxygen docs

The useful bits have been transformed to function definition comments.
The style guide stub has been added to the regular docs build.
parent d6b3a60f
......@@ -30,7 +30,6 @@ option(GLFW_BUILD_TESTS "Build the GLFW test programs" ON)
option(GLFW_BUILD_DOCS "Build the GLFW documentation" ON)
option(GLFW_INSTALL "Generate installation target" ON)
option(GLFW_VULKAN_STATIC "Use the Vulkan loader statically linked into application" OFF)
option(GLFW_DOCUMENT_INTERNALS "Include internals in documentation" OFF)
if (UNIX)
option(GLFW_USE_OSMESA "Use OSMesa for offscreen context creation" OFF)
......
......@@ -14,13 +14,8 @@ set(glfw_DOCS_SOURCES
"${GLFW_SOURCE_DIR}/docs/window.dox"
"${GLFW_SOURCE_DIR}/docs/input.dox"
"${GLFW_SOURCE_DIR}/docs/vulkan.dox"
"${GLFW_SOURCE_DIR}/docs/compat.dox")
if (GLFW_DOCUMENT_INTERNALS)
list(APPEND glfw_DOCS_SOURCES
"${GLFW_SOURCE_DIR}/docs/internal.dox"
"${GLFW_SOURCE_DIR}/src/internal.h")
endif()
"${GLFW_SOURCE_DIR}/docs/compat.dox"
"${GLFW_SOURCE_DIR}/docs/internal.dox")
foreach(arg ${glfw_DOCS_SOURCES})
set(GLFW_DOCS_SOURCES "${GLFW_DOCS_SOURCES} \\\n\"${arg}\"")
......
......@@ -19,8 +19,7 @@ The public interface uses the OpenGL naming conventions except with GLFW and
glfw instead of GL and gl. For struct members, where OpenGL sets no precedent,
it use headless camel case.
Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
`GLFW_RED_BITS`
Examples: `glfwCreateWindow`, `GLFWwindow`, `GLFW_RED_BITS`
@section internals_native Native interface
......@@ -34,7 +33,7 @@ The function names of the native interface are similar to those of the public
interface, but embeds the name of the interface that the returned handle is
from.
Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
Examples: `glfwGetX11Window`, `glfwGetWGLContext`
@section internals_internal Internal interface
......@@ -50,7 +49,7 @@ a `_GLFWlibrary` struct named `_glfw`.
The internal interface uses the same style as the public interface, except all
global names have a leading underscore.
Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
Examples: `_glfwIsValidContextConfig`, `_GLFWwindow`, `_glfw.monitorCount`
@section internals_platform Platform interface
......@@ -67,7 +66,7 @@ perform platform-specific operations on some or all platforms. The are also
named the same except that the glfw function prefix is replaced by
_glfwPlatform.
Examples: @ref _glfwPlatformCreateWindow
Examples: `_glfwPlatformCreateWindow`
The platform interface also defines structs that contain platform-specific
global and per-object state. Their names mirror those of the internal
......@@ -79,7 +78,7 @@ These structs are incorporated as members into the internal interface structs
using special macros that name them after the specific interface used. This
prevents shared code from accidentally using these members.
Examples: `window.win32.handle`, `_glfw.x11.display`
Examples: `window->win32.handle`, `_glfw.x11.display`
@section internals_event Event interface
......@@ -91,7 +90,7 @@ application, either via callbacks, via window state changes or both.
The function names of the event interface use a `_glfwInput` prefix and the
ObjectEvent pattern.
Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
Examples: `_glfwInputWindowFocus`, `_glfwInputCursorPos`
@section internals_static Static functions
......@@ -99,7 +98,7 @@ Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
Static functions may be used by any interface and have no prefixes or suffixes.
These use headless camel case.
Examples: `clearScrollOffsets`
Examples: `isValidElementForJoystick`
@section internals_config Configuration macros
......@@ -111,6 +110,6 @@ which is generated from the `glfw_config.h.in` file by CMake.
Configuration macros the same style as tokens in the public interface, except
with a leading underscore.
Examples: `_GLFW_USE_HYBRID_HPG`
Examples: `_GLFW_WIN32`, `_GLFW_BUILD_DLL`
*/
......@@ -38,6 +38,12 @@
////// GLFW internal API //////
//////////////////////////////////////////////////////////////////////////
// Checks whether the desired context attributes are valid
//
// This function checks things like whether the specified client API version
// exists and whether all relevant options have supported and non-conflicting
// values
//
GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
{
if (ctxconfig->source != GLFW_NATIVE_CONTEXT_API &&
......@@ -155,6 +161,8 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
return GLFW_TRUE;
}
// Chooses the framebuffer config that best matches the desired one
//
const _GLFWfbconfig* _glfwChooseFBConfig(const _GLFWfbconfig* desired,
const _GLFWfbconfig* alternatives,
unsigned int count)
......@@ -321,6 +329,8 @@ const _GLFWfbconfig* _glfwChooseFBConfig(const _GLFWfbconfig* desired,
return closest;
}
// Retrieves the attributes of the current context
//
GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
const _GLFWctxconfig* ctxconfig)
{
......@@ -555,6 +565,8 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
return GLFW_TRUE;
}
// Searches an extension string for the specified extension
//
GLFWbool _glfwStringInExtensionString(const char* string, const char* extensions)
{
const char* start = extensions;
......
......@@ -35,8 +35,9 @@
#include <assert.h>
// The global variables below comprise all global data in GLFW.
// Any other global variable is a bug.
// The global variables below comprise all mutable global data in GLFW
//
// Any other global variable is a bug
// Global state shared between compilation units of GLFW
//
......
......@@ -224,6 +224,8 @@ static GLFWbool parseMapping(_GLFWmapping* mapping, const char* string)
////// GLFW event API //////
//////////////////////////////////////////////////////////////////////////
// Notifies shared code of a physical key event
//
void _glfwInputKey(_GLFWwindow* window, int key, int scancode, int action, int mods)
{
if (key >= 0 && key <= GLFW_KEY_LAST)
......@@ -252,6 +254,9 @@ void _glfwInputKey(_GLFWwindow* window, int key, int scancode, int action, int m
window->callbacks.key((GLFWwindow*) window, key, scancode, action, mods);
}
// Notifies shared code of a Unicode codepoint input event
// The 'plain' parameter determines whether to emit a regular character event
//
void _glfwInputChar(_GLFWwindow* window, unsigned int codepoint, int mods, GLFWbool plain)
{
if (codepoint < 32 || (codepoint > 126 && codepoint < 160))
......@@ -270,12 +275,16 @@ void _glfwInputChar(_GLFWwindow* window, unsigned int codepoint, int mods, GLFWb
}
}
// Notifies shared code of a scroll event
//
void _glfwInputScroll(_GLFWwindow* window, double xoffset, double yoffset)
{
if (window->callbacks.scroll)
window->callbacks.scroll((GLFWwindow*) window, xoffset, yoffset);
}
// Notifies shared code of a mouse button click event
//
void _glfwInputMouseClick(_GLFWwindow* window, int button, int action, int mods)
{
if (button < 0 || button > GLFW_MOUSE_BUTTON_LAST)
......@@ -293,6 +302,9 @@ void _glfwInputMouseClick(_GLFWwindow* window, int button, int action, int mods)
window->callbacks.mouseButton((GLFWwindow*) window, button, action, mods);
}
// Notifies shared code of a cursor motion event
// The position is specified in client-area relative screen coordinates
//
void _glfwInputCursorPos(_GLFWwindow* window, double xpos, double ypos)
{
if (window->virtualCursorPosX == xpos && window->virtualCursorPosY == ypos)
......@@ -305,18 +317,24 @@ void _glfwInputCursorPos(_GLFWwindow* window, double xpos, double ypos)
window->callbacks.cursorPos((GLFWwindow*) window, xpos, ypos);
}
// Notifies shared code of a cursor enter/leave event
//
void _glfwInputCursorEnter(_GLFWwindow* window, GLFWbool entered)
{
if (window->callbacks.cursorEnter)
window->callbacks.cursorEnter((GLFWwindow*) window, entered);
}
// Notifies shared code of files or directories dropped on a window
//
void _glfwInputDrop(_GLFWwindow* window, int count, const char** paths)
{
if (window->callbacks.drop)
window->callbacks.drop((GLFWwindow*) window, count, paths);
}
// Notifies shared code of a joystick connection or disconnection
//
void _glfwInputJoystick(_GLFWjoystick* js, int event)
{
const int jid = (int) (js - _glfw.joysticks);
......@@ -325,16 +343,22 @@ void _glfwInputJoystick(_GLFWjoystick* js, int event)
_glfw.callbacks.joystick(jid, event);
}
// Notifies shared code of the new value of a joystick axis
//
void _glfwInputJoystickAxis(_GLFWjoystick* js, int axis, float value)
{
js->axes[axis] = value;
}
// Notifies shared code of the new value of a joystick button
//
void _glfwInputJoystickButton(_GLFWjoystick* js, int button, char value)
{
js->buttons[button] = value;
}
// Notifies shared code of the new value of a joystick hat
//
void _glfwInputJoystickHat(_GLFWjoystick* js, int hat, char value)
{
const int base = js->buttonCount + hat * 4;
......@@ -352,6 +376,8 @@ void _glfwInputJoystickHat(_GLFWjoystick* js, int hat, char value)
////// GLFW internal API //////
//////////////////////////////////////////////////////////////////////////
// Returns an available joystick object with arrays and name allocated
//
_GLFWjoystick* _glfwAllocJoystick(const char* name,
const char* guid,
int axisCount,
......@@ -386,6 +412,8 @@ _GLFWjoystick* _glfwAllocJoystick(const char* name,
return js;
}
// Frees arrays and name and flags the joystick object as unused
//
void _glfwFreeJoystick(_GLFWjoystick* js)
{
free(js->name);
......
This diff is collapsed.
......@@ -86,6 +86,8 @@ static GLFWbool refreshVideoModes(_GLFWmonitor* monitor)
////// GLFW event API //////
//////////////////////////////////////////////////////////////////////////
// Notifies shared code of a monitor connection or disconnection
//
void _glfwInputMonitor(_GLFWmonitor* monitor, int action, int placement)
{
if (action == GLFW_CONNECTED)
......@@ -141,6 +143,9 @@ void _glfwInputMonitor(_GLFWmonitor* monitor, int action, int placement)
_glfwFreeMonitor(monitor);
}
// Notifies shared code that a full screen window has acquired or released
// a monitor
//
void _glfwInputMonitorWindow(_GLFWmonitor* monitor, _GLFWwindow* window)
{
monitor->window = window;
......@@ -151,6 +156,8 @@ void _glfwInputMonitorWindow(_GLFWmonitor* monitor, _GLFWwindow* window)
////// GLFW internal API //////
//////////////////////////////////////////////////////////////////////////
// Allocates and returns a monitor object with the specified name and dimensions
//
_GLFWmonitor* _glfwAllocMonitor(const char* name, int widthMM, int heightMM)
{
_GLFWmonitor* monitor = calloc(1, sizeof(_GLFWmonitor));
......@@ -163,6 +170,8 @@ _GLFWmonitor* _glfwAllocMonitor(const char* name, int widthMM, int heightMM)
return monitor;
}
// Frees a monitor object and any data associated with it
//
void _glfwFreeMonitor(_GLFWmonitor* monitor)
{
if (monitor == NULL)
......@@ -176,6 +185,8 @@ void _glfwFreeMonitor(_GLFWmonitor* monitor)
free(monitor);
}
// Allocates red, green and blue value arrays of the specified size
//
void _glfwAllocGammaArrays(GLFWgammaramp* ramp, unsigned int size)
{
ramp->red = calloc(size, sizeof(unsigned short));
......@@ -184,6 +195,8 @@ void _glfwAllocGammaArrays(GLFWgammaramp* ramp, unsigned int size)
ramp->size = size;
}
// Frees the red, green and blue value arrays and clears the struct
//
void _glfwFreeGammaArrays(GLFWgammaramp* ramp)
{
free(ramp->red);
......@@ -193,6 +206,8 @@ void _glfwFreeGammaArrays(GLFWgammaramp* ramp)
memset(ramp, 0, sizeof(GLFWgammaramp));
}
// Chooses the video mode most closely matching the desired one
//
const GLFWvidmode* _glfwChooseVideoMode(_GLFWmonitor* monitor,
const GLFWvidmode* desired)
{
......@@ -243,11 +258,15 @@ const GLFWvidmode* _glfwChooseVideoMode(_GLFWmonitor* monitor,
return closest;
}
// Performs lexical comparison between two @ref GLFWvidmode structures
//
int _glfwCompareVideoModes(const GLFWvidmode* fm, const GLFWvidmode* sm)
{
return compareVideoModes(fm, sm);
}
// Splits a color depth into red, green and blue bit depths
//
void _glfwSplitBPP(int bpp, int* red, int* green, int* blue)
{
int delta;
......
......@@ -38,6 +38,8 @@
////// GLFW event API //////
//////////////////////////////////////////////////////////////////////////
// Notifies shared code that a window has lost or received input focus
//
void _glfwInputWindowFocus(_GLFWwindow* window, GLFWbool focused)
{
if (window->callbacks.focus)
......@@ -64,48 +66,68 @@ void _glfwInputWindowFocus(_GLFWwindow* window, GLFWbool focused)
}
}
// Notifies shared code that a window has moved
// The position is specified in client-area relative screen coordinates
//
void _glfwInputWindowPos(_GLFWwindow* window, int x, int y)
{
if (window->callbacks.pos)
window->callbacks.pos((GLFWwindow*) window, x, y);
}
// Notifies shared code that a window has been resized
// The size is specified in screen coordinates
//
void _glfwInputWindowSize(_GLFWwindow* window, int width, int height)
{
if (window->callbacks.size)
window->callbacks.size((GLFWwindow*) window, width, height);
}
// Notifies shared code that a window has been iconified or restored
//
void _glfwInputWindowIconify(_GLFWwindow* window, GLFWbool iconified)
{
if (window->callbacks.iconify)
window->callbacks.iconify((GLFWwindow*) window, iconified);
}
// Notifies shared code that a window has been maximized or restored
//
void _glfwInputWindowMaximize(_GLFWwindow* window, GLFWbool maximized)
{
if (window->callbacks.maximize)
window->callbacks.maximize((GLFWwindow*) window, maximized);
}
// Notifies shared code that a window framebuffer has been resized
// The size is specified in pixels
//
void _glfwInputFramebufferSize(_GLFWwindow* window, int width, int height)
{
if (window->callbacks.fbsize)
window->callbacks.fbsize((GLFWwindow*) window, width, height);
}
// Notifies shared code that a window content scale has changed
// The scale is specified as the ratio between the current and default DPI
//
void _glfwInputWindowContentScale(_GLFWwindow* window, float xscale, float yscale)
{
if (window->callbacks.scale)
window->callbacks.scale((GLFWwindow*) window, xscale, yscale);
}
// Notifies shared code that the window contents needs updating
//
void _glfwInputWindowDamage(_GLFWwindow* window)
{
if (window->callbacks.refresh)
window->callbacks.refresh((GLFWwindow*) window);
}
// Notifies shared code that the user wishes to close a window
//
void _glfwInputWindowCloseRequest(_GLFWwindow* window)
{
window->shouldClose = GLFW_TRUE;
......@@ -114,6 +136,8 @@ void _glfwInputWindowCloseRequest(_GLFWwindow* window)
window->callbacks.close((GLFWwindow*) window);
}
// Notifies shared code that a window has changed its desired monitor
//
void _glfwInputWindowMonitor(_GLFWwindow* window, _GLFWmonitor* monitor)
{
window->monitor = monitor;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment