Convert Doxygen code sections to Markdown

This commit is contained in:
Camilla Löwy
2024-02-13 20:57:45 +01:00
parent 611099f745
commit 1a0bae7fa8
11 changed files with 506 additions and 506 deletions

View File

@@ -19,9 +19,9 @@ behave differently in GLFW 3.
In the source files of your application where you use GLFW, you need to include
its header file.
@code{.c}
```c
#include <GLFW/glfw3.h>
@endcode
```
This header provides all the constants, types and function prototypes of the
GLFW API.
@@ -36,21 +36,21 @@ This example uses files generated by [glad](https://gen.glad.sh/). The GLFW
header can detect most such headers if they are included first and will then not
include the one from your development environment.
@code{.c}
```c
#include <glad/gl.h>
#include <GLFW/glfw3.h>
@endcode
```
To make sure there will be no header conflicts, you can define @ref
GLFW_INCLUDE_NONE before the GLFW header to explicitly disable inclusion of the
development environment header. This also allows the two headers to be included
in any order.
@code{.c}
```c
#define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h>
#include <glad/gl.h>
@endcode
```
### Initializing and terminating GLFW {#quick_init_term}
@@ -59,21 +59,21 @@ Before you can use most GLFW functions, the library must be initialized. On
successful initialization, `GLFW_TRUE` is returned. If an error occurred,
`GLFW_FALSE` is returned.
@code{.c}
```c
if (!glfwInit())
{
// Initialization failed
}
@endcode
```
Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be one and zero.
When you are done using GLFW, typically just before the application exits, you
need to terminate GLFW.
@code{.c}
```c
glfwTerminate();
@endcode
```
This destroys any remaining windows and releases any other resources allocated by
GLFW. After this call, you must initialize GLFW again before using any GLFW
@@ -90,21 +90,21 @@ In case a GLFW function fails, an error is reported to the GLFW error callback.
You can receive these reports with an error callback. This function must have
the signature below but may do anything permitted in other callbacks.
@code{.c}
```c
void error_callback(int error, const char* description)
{
fprintf(stderr, "Error: %s\n", description);
}
@endcode
```
Callback functions must be set, so GLFW knows to call them. The function to set
the error callback is one of the few GLFW functions that may be called before
initialization, which lets you be notified of errors both during and after
initialization.
@code{.c}
```c
glfwSetErrorCallback(error_callback);
@endcode
```
### Creating a window and context {#quick_create_window}
@@ -113,13 +113,13 @@ The window and its OpenGL context are created with a single call to @ref
glfwCreateWindow, which returns a handle to the created combined window and
context object
@code{.c}
```c
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
if (!window)
{
// Window or OpenGL context creation failed
}
@endcode
```
This creates a 640 by 480 windowed mode window with an OpenGL context. If
window or OpenGL context creation fails, `NULL` will be returned. You should
@@ -136,7 +136,7 @@ You can select the OpenGL profile by setting the `GLFW_OPENGL_PROFILE` hint.
This program uses the core profile as that is the only profile macOS supports
for OpenGL 3.x and 4.x.
@code{.c}
```c
glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
@@ -145,13 +145,13 @@ if (!window)
{
// Window or context creation failed
}
@endcode
```
When a window and context is no longer needed, destroy it.
@code{.c}
```c
glfwDestroyWindow(window);
@endcode
```
Once this function is called, no more events will be delivered for that window
and its handle becomes invalid.
@@ -161,9 +161,9 @@ and its handle becomes invalid.
Before you can use the OpenGL API, you must have a current OpenGL context.
@code{.c}
```c
glfwMakeContextCurrent(window);
@endcode
```
The context will remain current until you make another context current or until
the window owning the current context is destroyed.
@@ -174,9 +174,9 @@ a current context to load from. This example uses
[glad](https://github.com/Dav1dde/glad), but the same rule applies to all such
libraries.
@code{.c}
```c
gladLoadGL(glfwGetProcAddress);
@endcode
```
### Checking the window close flag {#quick_window_close}
@@ -189,12 +189,12 @@ Note that __the window isn't actually closed__, so you are expected to monitor
this flag and either destroy the window or give some kind of feedback to the
user.
@code{.c}
```c
while (!glfwWindowShouldClose(window))
{
// Keep running
}
@endcode
```
You can be notified when the user is attempting to close the window by setting
a close callback with @ref glfwSetWindowCloseCallback. The callback will be
@@ -211,19 +211,19 @@ Each window has a large number of callbacks that can be set to receive all the
various kinds of events. To receive key press and release events, create a key
callback function.
@code{.c}
```c
static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{
if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
glfwSetWindowShouldClose(window, GLFW_TRUE);
}
@endcode
```
The key callback, like other window related callbacks, are set per-window.
@code{.c}
```c
glfwSetKeyCallback(window, key_callback);
@endcode
```
In order for event callbacks to be called when events occur, you need to process
events as described below.
@@ -235,11 +235,11 @@ Once you have a current OpenGL context, you can use OpenGL normally. In this
tutorial, a multicolored rotating triangle will be rendered. The framebuffer
size needs to be retrieved for `glViewport`.
@code{.c}
```c
int width, height;
glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height);
@endcode
```
You can also set a framebuffer size callback using @ref
glfwSetFramebufferSizeCallback and be notified when the size changes.
@@ -263,9 +263,9 @@ returns the number of seconds since initialization. The time source used is the
most accurate on each platform and generally has micro- or nanosecond
resolution.
@code{.c}
```c
double time = glfwGetTime();
@endcode
```
### Swapping buffers {#quick_swap_buffers}
@@ -277,9 +277,9 @@ the one being displayed and the back buffer the one you render to.
When the entire frame has been rendered, the buffers need to be swapped with one
another, so the back buffer becomes the front buffer and vice versa.
@code{.c}
```c
glfwSwapBuffers(window);
@endcode
```
The swap interval indicates how many frames to wait until swapping the buffers,
commonly known as _vsync_. By default, the swap interval is zero, meaning
@@ -294,9 +294,9 @@ For these reasons, applications will typically want to set the swap interval to
one. It can be set to higher values, but this is usually not recommended,
because of the input latency it leads to.
@code{.c}
```c
glfwSwapInterval(1);
@endcode
```
This function acts on the current context and will fail unless a context is
current.
@@ -313,9 +313,9 @@ There are two methods for processing pending events; polling and waiting. This
example will use event polling, which processes only those events that have
already been received and then returns immediately.
@code{.c}
```c
glfwPollEvents();
@endcode
```
This is the best choice when rendering continually, like most games do. If
instead you only need to update your rendering once you have received new input,