diff --git a/CMakeLists.txt b/CMakeLists.txt index e150cdaf..f23a8626 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -19,7 +19,7 @@ find_package(Doxygen) option(GLFW_DOCUMENT_INTERNALS "Include internals in documentation" OFF) if (GLFW_DOCUMENT_INTERNALS) - set(GLFW_DOC_HEADERS "${GLFW_SOURCE_DIR}/src/internal.h") + set(GLFW_INTERNAL_DOCS "${GLFW_SOURCE_DIR}/src/internal.h ${GLFW_SOURCE_DIR}/docs/internal.dox") endif() if (APPLE) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 8da177d4..f3c9a0db 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -668,7 +668,17 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @GLFW_DOC_HEADERS@ @GLFW_SOURCE_DIR@/include/GLFW/ @GLFW_SOURCE_DIR@/docs/ +INPUT = @GLFW_INTERNAL_DOCS@ \ + @GLFW_SOURCE_DIR@/include/GLFW/glfw3.h \ + @GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \ + @GLFW_SOURCE_DIR@/docs/compat.dox \ + @GLFW_SOURCE_DIR@/docs/context.dox \ + @GLFW_SOURCE_DIR@/docs/main.dox \ + @GLFW_SOURCE_DIR@/docs/monitor.dox \ + @GLFW_SOURCE_DIR@/docs/moving.dox \ + @GLFW_SOURCE_DIR@/docs/news.dox \ + @GLFW_SOURCE_DIR@/docs/quick.dox \ + @GLFW_SOURCE_DIR@/docs/window.dox # 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 diff --git a/docs/internal.dox b/docs/internal.dox new file mode 100644 index 00000000..e32db621 --- /dev/null +++ b/docs/internal.dox @@ -0,0 +1,116 @@ +/*! + +@page internals Internal structure + +@tableofcontents + +There are several interfaces inside GLFW. Each interface has its own area of +responsibility and its own naming conventions. + + +@section internals_public Public interface + +The most well-known is the public interface, described in the glfw3.h header +file. This is implemented in source files shared by all platforms and these +files contain no platform-specific code. This code usually ends up calling the +platform and internal interfaces to do the actual work. + +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` + + +@section internals_native Native interface + +The [native interface](@ref native) is a small set of publicly available +but platform-specific functions, described in the glfw3native.h header file and +used to gain access to the underlying window, context and (on some platforms) +display handles used by the platform interface. + +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 + + +@section internals_internal Internal interface + +The internal interface consists of utility functions used by all other +interfaces. It is shared code implemented in the same shared source files as +the public and event interfaces. The internal interface is described in the +internal.h header file. + +The internal interface is in charge of GLFW's global data, which it stores in +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` + + +@section internals_platform Platform interface + +The platform interface implements all platform-specific operations as a service +to the public interface. This includes event processing. The platform +interface is never directly called by users of GLFW and never directly calls the +user's code. It is also prohibited from modifying the platform-independent part +of the internal structs. Instead, it calls the event interface when events +interesting to GLFW are received. + +The platform interface mirrors those parts of the public interface that needs to +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 + +The platform interface also defines structs that contain platform-specific +global and per-object state. Their names mirror those of the internal +interface, except that an interface-specific suffix is added. + +Examples: `_GLFWwindowX11`, `_GLFWcontextWGL` + +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` + + +@section internals_event Event interface + +The event interface is implemented in the same shared source files as the public +interface and is responsible for delivering the events it receives to the user, +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 + + +@section internals_static Static functions + +Static functions may be used by any interface and have no prefixes or suffixes. +These use headless camel case. + +Examples: `clearScrollOffsets` + + +@section internals_config Configuration macros + +GLFW uses a number of configuration macros to select at compile time which +interfaces and code paths to use. They are defined in the config.h header file, +which is generated from the `config.h.in` file by CMake. + +Configuration macros the same style as tokens in the public interface, except +with a leading underscore. + +Examples: `_GLFW_HAS_GLXGETPROCADDRESS` + +*/