mirror of
https://github.com/glfw/glfw.git
synced 2026-02-17 21:12:34 +01:00
Convert Doxygen code sections to Markdown
This commit is contained in:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user