Platformer in OpenGL
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

116 lines
4.2 KiB

5 years ago
  1. /*!
  2. @page internals_guide Internal structure
  3. @tableofcontents
  4. There are several interfaces inside GLFW. Each interface has its own area of
  5. responsibility and its own naming conventions.
  6. @section internals_public Public interface
  7. The most well-known is the public interface, described in the glfw3.h header
  8. file. This is implemented in source files shared by all platforms and these
  9. files contain no platform-specific code. This code usually ends up calling the
  10. platform and internal interfaces to do the actual work.
  11. The public interface uses the OpenGL naming conventions except with GLFW and
  12. glfw instead of GL and gl. For struct members, where OpenGL sets no precedent,
  13. it use headless camel case.
  14. Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
  15. `GLFW_RED_BITS`
  16. @section internals_native Native interface
  17. The [native interface](@ref native) is a small set of publicly available
  18. but platform-specific functions, described in the glfw3native.h header file and
  19. used to gain access to the underlying window, context and (on some platforms)
  20. display handles used by the platform interface.
  21. The function names of the native interface are similar to those of the public
  22. interface, but embeds the name of the interface that the returned handle is
  23. from.
  24. Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
  25. @section internals_internal Internal interface
  26. The internal interface consists of utility functions used by all other
  27. interfaces. It is shared code implemented in the same shared source files as
  28. the public and event interfaces. The internal interface is described in the
  29. internal.h header file.
  30. The internal interface is in charge of GLFW's global data, which it stores in
  31. a `_GLFWlibrary` struct named `_glfw`.
  32. The internal interface uses the same style as the public interface, except all
  33. global names have a leading underscore.
  34. Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
  35. @section internals_platform Platform interface
  36. The platform interface implements all platform-specific operations as a service
  37. to the public interface. This includes event processing. The platform
  38. interface is never directly called by application code and never directly calls
  39. application-provided callbacks. It is also prohibited from modifying the
  40. platform-independent part of the internal structs. Instead, it calls the event
  41. interface when events interesting to GLFW are received.
  42. The platform interface mirrors those parts of the public interface that needs to
  43. perform platform-specific operations on some or all platforms. The are also
  44. named the same except that the glfw function prefix is replaced by
  45. _glfwPlatform.
  46. Examples: @ref _glfwPlatformCreateWindow
  47. The platform interface also defines structs that contain platform-specific
  48. global and per-object state. Their names mirror those of the internal
  49. interface, except that an interface-specific suffix is added.
  50. Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
  51. These structs are incorporated as members into the internal interface structs
  52. using special macros that name them after the specific interface used. This
  53. prevents shared code from accidentally using these members.
  54. Examples: `window.win32.handle`, `_glfw.x11.display`
  55. @section internals_event Event interface
  56. The event interface is implemented in the same shared source files as the public
  57. interface and is responsible for delivering the events it receives to the
  58. application, either via callbacks, via window state changes or both.
  59. The function names of the event interface use a `_glfwInput` prefix and the
  60. ObjectEvent pattern.
  61. Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
  62. @section internals_static Static functions
  63. Static functions may be used by any interface and have no prefixes or suffixes.
  64. These use headless camel case.
  65. Examples: `clearScrollOffsets`
  66. @section internals_config Configuration macros
  67. GLFW uses a number of configuration macros to select at compile time which
  68. interfaces and code paths to use. They are defined in the glfw_config.h header file,
  69. which is generated from the `glfw_config.h.in` file by CMake.
  70. Configuration macros the same style as tokens in the public interface, except
  71. with a leading underscore.
  72. Examples: `_GLFW_HAS_XF86VM`
  73. */