mirror of
https://github.com/glfw/glfw.git
synced 2024-11-11 04:53:50 +00:00
Documentation work
This commit is contained in:
parent
4f5731ac39
commit
999f3556fd
18
README.md
18
README.md
@ -10,16 +10,18 @@ GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
|
|||||||
application development. It provides a simple, platform-independent API for
|
application development. It provides a simple, platform-independent API for
|
||||||
creating windows, contexts and surfaces, reading input, handling events, etc.
|
creating windows, contexts and surfaces, reading input, handling events, etc.
|
||||||
|
|
||||||
The current stable release is version 3.2. See the
|
GLFW is licensed under the [zlib/libpng
|
||||||
[downloads](http://www.glfw.org/download.html) page for details and files, or
|
license](https://opensource.org/licenses/Zlib).
|
||||||
fetch the `latest` branch, which always points to the latest stable release.
|
|
||||||
Each release starting with 3.0 also has a corresponding [annotated
|
|
||||||
tag](https://github.com/glfw/glfw/releases) with source and binary archives.
|
|
||||||
|
|
||||||
This is version 3.2.1, which adds support for statically linking the Vulkan
|
This is version 3.2.1, which adds support for statically linking the Vulkan
|
||||||
loader and fixes for a number of bugs that together affect all supported
|
loader and fixes for a number of bugs that together affect all supported
|
||||||
platforms.
|
platforms.
|
||||||
|
|
||||||
|
See the [downloads](http://www.glfw.org/download.html) page for details and
|
||||||
|
files, or fetch the `latest` branch, which always points to the latest stable
|
||||||
|
release. Each release starting with 3.0 also has a corresponding [annotated
|
||||||
|
tag](https://github.com/glfw/glfw/releases) with source and binary archives.
|
||||||
|
|
||||||
If you are new to GLFW, you may find the
|
If you are new to GLFW, you may find the
|
||||||
[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW
|
[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW
|
||||||
3 useful. If you have used GLFW 2 in the past, there is a
|
3 useful. If you have used GLFW 2 in the past, there is a
|
||||||
@ -133,15 +135,15 @@ On [glfw.org](http://www.glfw.org/) you can find the latest version of GLFW, as
|
|||||||
well as news, documentation and other information about the project.
|
well as news, documentation and other information about the project.
|
||||||
|
|
||||||
If you have questions related to the use of GLFW, we have a
|
If you have questions related to the use of GLFW, we have a
|
||||||
[support forum](http://discourse.glfw.org/), and the IRC
|
[forum](http://discourse.glfw.org/), and the `#glfw` IRC channel on
|
||||||
channel `#glfw` on [Freenode](http://freenode.net/).
|
[Freenode](http://freenode.net/).
|
||||||
|
|
||||||
If you have a bug to report, a patch to submit or a feature you'd like to
|
If you have a bug to report, a patch to submit or a feature you'd like to
|
||||||
request, please file it in the
|
request, please file it in the
|
||||||
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
|
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
|
||||||
|
|
||||||
Finally, if you're interested in helping out with the development of GLFW or
|
Finally, if you're interested in helping out with the development of GLFW or
|
||||||
porting it to your favorite platform, join us on GitHub or IRC.
|
porting it to your favorite platform, join us on the forum, GitHub or IRC.
|
||||||
|
|
||||||
|
|
||||||
## Acknowledgements
|
## Acknowledgements
|
||||||
|
@ -103,7 +103,8 @@ and only for compatibility with legacy code. GLU has been deprecated and should
|
|||||||
not be used in new code.
|
not be used in new code.
|
||||||
|
|
||||||
@note GLFW does not provide any of the API headers mentioned above. They must
|
@note GLFW does not provide any of the API headers mentioned above. They must
|
||||||
be provided by your development environment or your OpenGL or OpenGL ES SDK.
|
be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
|
||||||
|
SDK.
|
||||||
|
|
||||||
@note None of these macros may be defined during the compilation of GLFW itself.
|
@note None of these macros may be defined during the compilation of GLFW itself.
|
||||||
If your build includes GLFW and you define any these in your build files, make
|
If your build includes GLFW and you define any these in your build files, make
|
||||||
@ -184,21 +185,35 @@ the include directory for the GLFW header and, when applicable, the
|
|||||||
target_link_libraries(myapp glfw)
|
target_link_libraries(myapp glfw)
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
Note that it does not include GLU, as GLFW does not use it. If your application
|
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
||||||
needs GLU, you can find it by requiring the OpenGL package.
|
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
|
||||||
|
If your application calls OpenGL directly, instead of using a modern
|
||||||
|
[extension loader library](@ref context_glext_auto) you can find it by requiring
|
||||||
|
the OpenGL package.
|
||||||
|
|
||||||
@code{.cmake}
|
@code{.cmake}
|
||||||
find_package(OpenGL REQUIRED)
|
find_package(OpenGL REQUIRED)
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
If GLU is found, the `OPENGL_GLU_FOUND` variable is true and the
|
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
||||||
`OPENGL_INCLUDE_DIR` and `OPENGL_glu_LIBRARY` cache variables can be used.
|
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
||||||
|
|
||||||
@code{.cmake}
|
@code{.cmake}
|
||||||
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
|
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
|
||||||
|
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
The OpenGL CMake package also looks for GLU. If GLU is found, the
|
||||||
|
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
|
||||||
|
`OPENGL_glu_LIBRARY` cache variables can be used.
|
||||||
|
|
||||||
|
@code{.cmake}
|
||||||
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
@note GLU has been deprecated and should not be used in new code, but some
|
||||||
|
legacy code requires it.
|
||||||
|
|
||||||
|
|
||||||
@subsection build_link_cmake_package With CMake and installed GLFW binaries
|
@subsection build_link_cmake_package With CMake and installed GLFW binaries
|
||||||
|
|
||||||
@ -213,30 +228,35 @@ target files generated when GLFW is installed.
|
|||||||
find_package(glfw3 3.2 REQUIRED)
|
find_package(glfw3 3.2 REQUIRED)
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
Once GLFW has been located, link against it with the `glfw` target. This adds
|
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
||||||
all link-time dependencies of GLFW as it is currently configured, the include
|
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
|
||||||
directory for the GLFW header and, when applicable, the
|
If your application calls OpenGL directly, instead of using a modern
|
||||||
[GLFW_DLL](@ref build_macros) macro.
|
[extension loader library](@ref context_glext_auto) you can find it by requiring
|
||||||
|
the OpenGL package.
|
||||||
@code{.cmake}
|
|
||||||
target_link_libraries(myapp glfw)
|
|
||||||
@endcode
|
|
||||||
|
|
||||||
Note that it does not include GLU, as GLFW does not use it. If your application
|
|
||||||
needs GLU, you can find it by requiring the OpenGL package.
|
|
||||||
|
|
||||||
@code{.cmake}
|
@code{.cmake}
|
||||||
find_package(OpenGL REQUIRED)
|
find_package(OpenGL REQUIRED)
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
If GLU is found, the `OPENGL_GLU_FOUND` variable is true and the
|
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
||||||
`OPENGL_INCLUDE_DIR` and `OPENGL_glu_LIBRARY` cache variables can be used.
|
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
||||||
|
|
||||||
@code{.cmake}
|
@code{.cmake}
|
||||||
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
|
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
|
||||||
|
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
The OpenGL CMake package also looks for GLU. If GLU is found, the
|
||||||
|
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
|
||||||
|
`OPENGL_glu_LIBRARY` cache variables can be used.
|
||||||
|
|
||||||
|
@code{.cmake}
|
||||||
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
@note GLU has been deprecated and should not be used in new code, but some
|
||||||
|
legacy code requires it.
|
||||||
|
|
||||||
|
|
||||||
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
|
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
|
||||||
|
|
||||||
@ -268,8 +288,9 @@ You can also use the `glfw3.pc` file without installing it first, by using the
|
|||||||
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
The dependencies do not include GLU, as GLFW does not use it. On OS X, GLU is
|
The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
|
||||||
built into the OpenGL framework, so if you need GLU you don't need to do
|
ES or Vulkan libraries it needs at runtime and does not use GLU. On OS X, GLU
|
||||||
|
is built into the OpenGL framework, so if you need GLU you don't need to do
|
||||||
anything extra. If you need GLU and are using Linux or BSD, you should add the
|
anything extra. If you need GLU and are using Linux or BSD, you should add the
|
||||||
`glu` pkg-config package.
|
`glu` pkg-config package.
|
||||||
|
|
||||||
@ -277,6 +298,9 @@ anything extra. If you need GLU and are using Linux or BSD, you should add the
|
|||||||
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
|
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
@note GLU has been deprecated and should not be used in new code, but some
|
||||||
|
legacy code requires it.
|
||||||
|
|
||||||
If you are using the static version of the GLFW library, make sure you don't
|
If you are using the static version of the GLFW library, make sure you don't
|
||||||
link statically against GLU.
|
link statically against GLU.
|
||||||
|
|
||||||
|
@ -80,7 +80,8 @@ Once you have a full screen window, you can change its resolution, refresh rate
|
|||||||
and monitor with @ref glfwSetWindowMonitor. If you just need change its
|
and monitor with @ref glfwSetWindowMonitor. If you just need change its
|
||||||
resolution you can also call @ref glfwSetWindowSize. In all cases, the new
|
resolution you can also call @ref glfwSetWindowSize. In all cases, the new
|
||||||
video mode will be selected the same way as the video mode chosen by @ref
|
video mode will be selected the same way as the video mode chosen by @ref
|
||||||
glfwCreateWindow.
|
glfwCreateWindow. If the window has an OpenGL or OpenGL ES context, it will be
|
||||||
|
unaffected.
|
||||||
|
|
||||||
By default, the original video mode of the monitor will be restored and the
|
By default, the original video mode of the monitor will be restored and the
|
||||||
window iconified if it loses input focus, to allow the user to switch back to
|
window iconified if it loses input focus, to allow the user to switch back to
|
||||||
|
@ -1743,6 +1743,10 @@ GLFWAPI void glfwWindowHint(int hint, int value);
|
|||||||
* screen windows, including the creation of so called _windowed full screen_
|
* screen windows, including the creation of so called _windowed full screen_
|
||||||
* or _borderless full screen_ windows, see @ref window_windowed_full_screen.
|
* or _borderless full screen_ windows, see @ref window_windowed_full_screen.
|
||||||
*
|
*
|
||||||
|
* Once you have created the window, you can switch it between windowed and
|
||||||
|
* full screen mode with @ref glfwSetWindowMonitor. If the window has an
|
||||||
|
* OpenGL or OpenGL ES context, it will be unaffected.
|
||||||
|
*
|
||||||
* By default, newly created windows use the placement recommended by the
|
* By default, newly created windows use the placement recommended by the
|
||||||
* window system. To create the window at a specific position, make it
|
* window system. To create the window at a specific position, make it
|
||||||
* initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window
|
* initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window
|
||||||
@ -2394,8 +2398,8 @@ GLFWAPI void glfwFocusWindow(GLFWwindow* window);
|
|||||||
* in full screen on.
|
* in full screen on.
|
||||||
*
|
*
|
||||||
* @param[in] window The window to query.
|
* @param[in] window The window to query.
|
||||||
* @return The monitor, or `NULL` if the window is in windowed mode or an error
|
* @return The monitor, or `NULL` if the window is in windowed mode or an
|
||||||
* occurred.
|
* [error](@ref error_handling) occurred.
|
||||||
*
|
*
|
||||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
||||||
*
|
*
|
||||||
@ -3359,7 +3363,7 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
|
|||||||
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
|
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
|
||||||
* callback.
|
* callback.
|
||||||
* @return The previously set callback, or `NULL` if no callback was set or an
|
* @return The previously set callback, or `NULL` if no callback was set or an
|
||||||
* error occurred.
|
* [error](@ref error_handling) occurred.
|
||||||
*
|
*
|
||||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
||||||
*
|
*
|
||||||
@ -3538,8 +3542,10 @@ GLFWAPI int glfwJoystickPresent(int joy);
|
|||||||
*
|
*
|
||||||
* @param[in] joy The [joystick](@ref joysticks) to query.
|
* @param[in] joy The [joystick](@ref joysticks) to query.
|
||||||
* @param[out] count Where to store the number of axis values in the returned
|
* @param[out] count Where to store the number of axis values in the returned
|
||||||
* array. This is set to zero if an error occurred.
|
* array. This is set to zero if the joystick is not present or an error
|
||||||
* @return An array of axis values, or `NULL` if the joystick is not present.
|
* occurred.
|
||||||
|
* @return An array of axis values, or `NULL` if the joystick is not present or
|
||||||
|
* an [error](@ref error_handling) occurred.
|
||||||
*
|
*
|
||||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||||
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||||
@ -3570,8 +3576,10 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
|
|||||||
*
|
*
|
||||||
* @param[in] joy The [joystick](@ref joysticks) to query.
|
* @param[in] joy The [joystick](@ref joysticks) to query.
|
||||||
* @param[out] count Where to store the number of button states in the returned
|
* @param[out] count Where to store the number of button states in the returned
|
||||||
* array. This is set to zero if an error occurred.
|
* array. This is set to zero if the joystick is not present or an error
|
||||||
* @return An array of button states, or `NULL` if the joystick is not present.
|
* occurred.
|
||||||
|
* @return An array of button states, or `NULL` if the joystick is not present
|
||||||
|
* or an [error](@ref error_handling) occurred.
|
||||||
*
|
*
|
||||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||||
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||||
@ -3604,7 +3612,7 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count);
|
|||||||
*
|
*
|
||||||
* @param[in] joy The [joystick](@ref joysticks) to query.
|
* @param[in] joy The [joystick](@ref joysticks) to query.
|
||||||
* @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
|
* @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
|
||||||
* is not present.
|
* is not present or an [error](@ref error_handling) occurred.
|
||||||
*
|
*
|
||||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||||
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||||
|
Loading…
Reference in New Issue
Block a user