mirror of
https://github.com/glfw/glfw.git
synced 2024-11-22 04:54:35 +00:00
Documentation work
This commit is contained in:
Camilla Berglund
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
|
||||
creating windows, contexts and surfaces, reading input, handling events, etc.
|
||||
|
||||
The current stable release is version 3.2. 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.
|
||||
GLFW is licensed under the [zlib/libpng
|
||||
license](https://opensource.org/licenses/Zlib).
|
||||
|
||||
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
|
||||
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
|
||||
[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
|
||||
@ -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.
|
||||
|
||||
If you have questions related to the use of GLFW, we have a
|
||||
[support forum](http://discourse.glfw.org/), and the IRC
|
||||
channel `#glfw` on [Freenode](http://freenode.net/).
|
||||
[forum](http://discourse.glfw.org/), and the `#glfw` IRC channel on
|
||||
[Freenode](http://freenode.net/).
|
||||
|
||||
If you have a bug to report, a patch to submit or a feature you'd like to
|
||||
request, please file it in the
|
||||
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
|
||||
|
||||
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
|
||||
|
||||
@ -103,7 +103,8 @@ and only for compatibility with legacy code. GLU has been deprecated and should
|
||||
not be used in new code.
|
||||
|
||||
@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.
|
||||
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)
|
||||
@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.
|
||||
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
||||
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}
|
||||
find_package(OpenGL REQUIRED)
|
||||
@endcode
|
||||
|
||||
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.
|
||||
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
||||
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
||||
|
||||
@code{.cmake}
|
||||
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})
|
||||
@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
|
||||
|
||||
@ -213,30 +228,35 @@ target files generated when GLFW is installed.
|
||||
find_package(glfw3 3.2 REQUIRED)
|
||||
@endcode
|
||||
|
||||
Once GLFW has been located, link against it with the `glfw` target. This adds
|
||||
all link-time dependencies of GLFW as it is currently configured, the include
|
||||
directory for the GLFW header and, when applicable, the
|
||||
[GLFW_DLL](@ref build_macros) macro.
|
||||
|
||||
@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.
|
||||
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
||||
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}
|
||||
find_package(OpenGL REQUIRED)
|
||||
@endcode
|
||||
|
||||
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.
|
||||
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
||||
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
||||
|
||||
@code{.cmake}
|
||||
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})
|
||||
@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
|
||||
|
||||
@ -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`
|
||||
@endcode
|
||||
|
||||
The dependencies do not include GLU, as GLFW does not use it. On OS X, GLU is
|
||||
built into the OpenGL framework, so if you need GLU you don't need to do
|
||||
The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
|
||||
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
|
||||
`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`
|
||||
@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
|
||||
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
|
||||
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
|
||||
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
|
||||
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_
|
||||
* 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
|
||||
* window system. To create the window at a specific position, make it
|
||||
* initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window
|
||||
@ -2394,8 +2398,8 @@ GLFWAPI void glfwFocusWindow(GLFWwindow* window);
|
||||
* in full screen on.
|
||||
*
|
||||
* @param[in] window The window to query.
|
||||
* @return The monitor, or `NULL` if the window is in windowed mode or an error
|
||||
* occurred.
|
||||
* @return The monitor, or `NULL` if the window is in windowed mode or an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @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
|
||||
* callback.
|
||||
* @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.
|
||||
*
|
||||
@ -3538,8 +3542,10 @@ GLFWAPI int glfwJoystickPresent(int joy);
|
||||
*
|
||||
* @param[in] joy The [joystick](@ref joysticks) to query.
|
||||
* @param[out] count Where to store the number of axis values in the returned
|
||||
* array. This is set to zero if an error occurred.
|
||||
* @return An array of axis values, or `NULL` if the joystick is not present.
|
||||
* array. This is set to zero if the joystick is not present or an error
|
||||
* 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
|
||||
* 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[out] count Where to store the number of button states in the returned
|
||||
* array. This is set to zero if an error occurred.
|
||||
* @return An array of button states, or `NULL` if the joystick is not present.
|
||||
* array. This is set to zero if the joystick is not present or an error
|
||||
* 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
|
||||
* 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.
|
||||
* @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
|
||||
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user