Simplify header names

1 files changed, 148 insertions, 0 deletions

diff --git a/include/pugl/vulkan.h b/include/pugl/vulkan.h
new file mode 100644
index 0000000..a2755f9
--- /dev/null
+++ b/include/pugl/vulkan.h
@@ -0,0 +1,148 @@
+/*
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted, provided that the above
+  copyright notice and this permission notice appear in all copies.
+
+  THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+   @file vulkan.h Vulkan-specific API.
+
+   Note that this header includes Vulkan headers, so if you are writing a
+   program or plugin that dynamically loads vulkan, you should first define
+   `VK_NO_PROTOTYPES` before including it.
+*/
+
+#ifndef PUGL_VULKAN_H
+#define PUGL_VULKAN_H
+
+#include "pugl/pugl.h"
+
+#include <vulkan/vulkan.h>
+
+PUGL_BEGIN_DECLS
+
+/**
+   @defgroup vulkan Vulkan
+   Vulkan graphics support.
+
+   Vulkan support differs from OpenGL because almost all most configuration is
+   done using the Vulkan API itself, rather than by setting view hints to
+   configure the context.  Pugl only provides a minimal loader for loading the
+   Vulkan library, and a portable function to create a Vulkan surface for a
+   view, which hides the platform-specific implementation details.
+
+   @ingroup pugl_c
+   @{
+*/
+
+/**
+   Dynamic Vulkan loader.
+
+   This can be used to dynamically load the Vulkan library.  Applications or
+   plugins should not link against the Vulkan library, but instead use this at
+   runtime.  This ensures that things will work on as many systems as possible,
+   and allows errors to be handled gracefully.
+
+   This is not a "loader" in the sense of loading all the required Vulkan
+   functions (which is the application's responsibility), but just a minimal
+   implementation to portably load the Vulkan library and get the two functions
+   that are used to load everything else.
+
+   Note that this owns the loaded Vulkan library, so it must outlive all use of
+   the Vulkan API.
+
+   @see https://www.khronos.org/registry/vulkan/specs/1.0/html/chap4.html
+*/
+typedef struct PuglVulkanLoaderImpl PuglVulkanLoader;
+
+/**
+   Create a new dynamic loader for Vulkan functions.
+
+   This dynamically loads the Vulkan library and gets the load functions from it.
+
+   @return A new Vulkan loader, or null on failure.
+*/
+PUGL_API PuglVulkanLoader*
+puglNewVulkanLoader(PuglWorld* world);
+
+/**
+   Free a loader created with puglNewVulkanLoader().
+
+   Note that this closes the Vulkan library, so no Vulkan objects or API may be
+   used after this is called.
+*/
+PUGL_API void
+puglFreeVulkanLoader(PuglVulkanLoader* loader);
+
+/**
+   Return the `vkGetInstanceProcAddr` function.
+
+   @return Null if the Vulkan library does not contain this function (which is
+   unlikely and indicates a broken system).
+*/
+PUGL_API PFN_vkGetInstanceProcAddr
+puglGetInstanceProcAddrFunc(const PuglVulkanLoader* loader);
+
+/**
+   Return the `vkGetDeviceProcAddr` function.
+
+   @return Null if the Vulkan library does not contain this function (which is
+   unlikely and indicates a broken system).
+*/
+PUGL_API PFN_vkGetDeviceProcAddr
+puglGetDeviceProcAddrFunc(const PuglVulkanLoader* loader);
+
+/**
+   Return the Vulkan instance extensions required to draw to a PuglView.
+
+   This simply returns static strings, it does not access Vulkan or the window
+   system.  The returned array always contains at least "VK_KHR_surface".
+
+   @param[out] count The number of extensions in the returned array.
+   @return An array of extension name strings.
+*/
+PUGL_API const char* const*
+puglGetInstanceExtensions(uint32_t* count);
+
+/**
+   Create a Vulkan surface for a Pugl view.
+
+   @param loader The loader for Vulkan functions.
+   @param view The view the surface is to be displayed on.
+   @param instance The Vulkan instance.
+   @param allocator Vulkan allocation callbacks, may be NULL.
+   @param[out] surface Pointed to a newly created Vulkan surface.
+   @return `VK_SUCCESS` on success, or a Vulkan error code.
+*/
+PUGL_API VkResult
+puglCreateSurface(const PuglVulkanLoader*      loader,
+                  PuglView*                    view,
+                  VkInstance                   instance,
+                  const VkAllocationCallbacks* allocator,
+                  VkSurfaceKHR*                surface);
+
+/**
+   Vulkan graphics backend.
+
+   Pass the returned value to puglSetBackend() to draw to a view with Vulkan.
+*/
+PUGL_API PUGL_CONST_FUNC const PuglBackend*
+puglVulkanBackend(void);
+
+/**
+   @}
+*/
+
+PUGL_END_DECLS
+
+#endif // PUGL_VULKAN_H