mirror of https://github.com/mosra/magnum.git
Browse Source
Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.pull/234/head
Vladimír Vondruš
6 years ago
10 changed files with 560 additions and 48 deletions
@ -0,0 +1,102 @@
|
||||
/* |
||||
This file is part of Magnum. |
||||
|
||||
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, |
||||
2020 Vladimír Vondruš <mosra@centrum.cz> |
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a |
||||
copy of this software and associated documentation files (the "Software"), |
||||
to deal in the Software without restriction, including without limitation |
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
||||
and/or sell copies of the Software, and to permit persons to whom the |
||||
Software is furnished to do so, subject to the following conditions: |
||||
|
||||
The above copyright notice and this permission notice shall be included |
||||
in all copies or substantial portions of the Software. |
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
||||
DEALINGS IN THE SOFTWARE. |
||||
*/ |
||||
|
||||
namespace Magnum { |
||||
/** @page vulkan-wrapping Vulkan wrapping layer |
||||
@brief Overview of the base Vulkan wrapper API |
||||
|
||||
@tableofcontents |
||||
@m_footernavigation |
||||
|
||||
The @ref Magnum::Vk library is a thin but high-level abstraction of the |
||||
[Vulkan](https://www.khronos.org/vulkan/) GPU API, providing sane defaults with |
||||
ability to opt-in for greater control and performance. |
||||
|
||||
@section vulkan-wrapping-instance-device Instance and device wrappers |
||||
|
||||
Compared to OpenGL, which has a concept of "current context", Vulkan doesn't |
||||
have any implicit globals. The @ref Vk library follows that, with each object |
||||
carrying a reference to a corresponding instance or device along. This was |
||||
chosen as a reasonable tradeoff between requiring an explicit instance/device |
||||
parameter in each API (which would be too error-prone and annoying to use) and |
||||
having an implicit thread-local instance/device (which would repeat the |
||||
well-known pain points of OpenGL). |
||||
|
||||
Vulkan API entrypoints aren't global either because each instance and device |
||||
can have a different set of enabled layers and extensions, and thus different |
||||
instance- and device-local function pointers. While the Vulkan specification |
||||
allows device-level functions to be queried on an instance and thus use the |
||||
same function pointers on a variety of devices, such workflow implies |
||||
additional dispatch overhead, and thus isn't recommended. Magnum instead |
||||
stores instance- and device-level function pointers locally in each |
||||
@ref Vk::Instance and @ref Vk::Device to avoid this overhead --- these are then |
||||
accessible through @ref Vk::Instance::operator->() "operator->()" on both: |
||||
|
||||
@snippet MagnumVk.cpp Instance-function-pointers |
||||
|
||||
For convenience and for easier interaction with 3rd party code, such pointers |
||||
can be made global by calling @ref Vk::Instance::populateGlobalFunctionPointers() |
||||
and @ref Vk::Device::populateGlobalFunctionPointers(), after which you can use |
||||
the `vk*` functions as usual. However, all implications coming from these being |
||||
tied to a particular instance/device still apply: |
||||
|
||||
@snippet MagnumVk.cpp Instance-global-function-pointers |
||||
|
||||
@section vulkan-wrapping-create-info CreateInfo structure wrappers |
||||
|
||||
In most cases, a`Vk::*CreateInfo` instance has all required fields set to valid |
||||
values upon construction, with everything else optional. One exception to this |
||||
rule is for example @ref Vk::DeviceCreateInfo, where the user is expected to |
||||
call @ref Vk::DeviceCreateInfo::addQueues() "addQueues()". |
||||
|
||||
@section vulkan-wrapping-raw Common interfaces for interaction with raw Vulkan code |
||||
|
||||
Each wrapped Vulkan object has a @ref Vk::Instance::handle() "handle()" getter, |
||||
giving back the underlying Vulkan handle such as @type_vk{Instance}. In |
||||
addition it's also implicitly convertible to that handle type, which means you |
||||
can pass it as-is to raw Vulkan APIs. You can also use |
||||
@ref Vk::Instance::release() "release()" to release its ownership and continue |
||||
to use it as a regular handle. Conversely, any Vulkan handle can be wrapped |
||||
into a first-class Magnum object using a corresponding |
||||
@ref Vk::Instance::wrap() "wrap()" function. |
||||
|
||||
Similarly, all @ref Vk::InstanceCreateInfo "Vk::*CreateInfo" wrapper classes |
||||
are convertible to a `Vk*CreateInfo` pointer in order to be easily passable |
||||
directly to Vulkan APIs. You can create them from an existing |
||||
`Vk*CreateInfo` instances as well, and use |
||||
@ref Vk::InstanceCreateInfo::operator->() "operator->()" to access the wrapped |
||||
structure to supply additional parameters not exposed by Magnum. However take |
||||
care to not clash with values and pointers already set: |
||||
|
||||
@snippet MagnumVk.cpp wrapping-extending-create-info |
||||
|
||||
To completely mitigate the overhead from instantiating wrapper `*CreateInfo` |
||||
classes, each of them can also be constructed using the @ref NoInit tag, which |
||||
will skip all initialization and leave the contents unspecified to be filled |
||||
later. Note that at that point you have the full responsibility to correctly |
||||
set up all members. |
||||
|
||||
*/ |
||||
} |
||||
Loading…
Reference in new issue