Awesome

Ashes

Ashes is a drop-in replacement or ICD to Vulkan.
It allows to write Vulkan code, and to select the rendering API that will be used.
It also comes with ashespp, a C++ wrapper for Vulkan.
To build it, you can use CMake.

Renderers available

Vulkan: Ashes is a passthrough, when using Vulkan rendering API, and it has no additional cost if dynamic loader is used.
OpenGL: From OpenGL 3.3 to OpenGL 4.6 (Core profile), it can be used directly as an ICD.
Direct3D 11: From feature level 11.0.

Supported platforms

Windows.
Linux.
MacOS.

How to use it

Three workflows are possible:

ICD mode

Just set the environment variable VK_ICD_FILENAMES to one of the jsons in Ashes' install dir, and you're done.

Drop-in replacement mode

You load Ashes' shared library instead of Vulkan's, and you're done.
The API selection will be done on first call of vkGetInstanceProcAddr (for dynamic loader), or on first Vulkan API call (for static loader).

Manual mode

You can ask for the list of loaded plugins, through a call to the function int ashEnumeratePlugins( uint32_t * count , AshPluginDescription * plugins );.
It works as Vulkan ones : if plugins is set to NULL, count will then contain the number of loaded plugins.

API

The following API is available, in ashes.h:

typedef struct AshPluginFeatures
{
	// Whether or not the plugin supports buffer ranges.
	VkBool32 hasBufferRange;
	// Whether or not the plugin supports image textures.
	VkBool32 hasImageTexture;
	// Whether or not the plugin supports vertex base instance.
	VkBool32 hasBaseInstance;
	// Whether or not the plugin supports clearing of single images.
	VkBool32 hasClearTexImage;
	// Whether or not the plugin supports compute shaders.
	VkBool32 hasComputeShaders;
	// Whether or not the plugin supports shader storage buffers.
	VkBool32 hasStorageBuffers;
	// Whether or not the plugin supports persistent mapping.
	VkBool32 supportsPersistentMapping;
	// The plugin's maximum supported shader language version.
	uint32_t maxShaderLanguageVersion;
} AshPluginFeatures;

typedef struct AshPluginSupport
{
	// The plugin's priority (from 1 (low) to 10 (high)).
	uint32_t priority;
	// Whether or not the plugin is supported.
	VkBool32 supported;
} AshPluginSupport;

typedef struct AshPluginDescription
{
	//The plugin's short name.
	char name[16];
	//The plugin's description.
	char description[64];
	//The plugin's main entry point.
	PFN_vkGetInstanceProcAddr getInstanceProcAddr;
	//The plugin's supported features.
	AshPluginFeatures features;
	//The plugin's static functions (for static loader support).
	AshPluginStaticFunction functions;
	//The plugin's support informations.
	AshPluginSupport support;
} AshPluginDescription;

// Enumerates the available rendering APIs.
typedef void( VKAPI_PTR * PFN_ashEnumeratePluginsDescriptions )( uint32_t *, AshPluginDescription * );
Ashes_API void VKAPI_PTR ashEnumeratePluginsDescriptions( uint32_t * count
	, AshPluginDescription * pDescriptions );

// Defines the active rendering API.
typedef VkResult( VKAPI_PTR * PFN_ashSelectPlugin )( AshPluginDescription );
Ashes_API VkResult VKAPI_PTR ashSelectPlugin( AshPluginDescription description );

// Retrieves the active rendering API informations.
typedef VkResult( VKAPI_PTR * PFN_ashGetPluginDescription )( AshPluginDescription * );
Ashes_API VkResult VKAPI_PTR ashGetCurrentPluginDescription( AshPluginDescription * description );

From this, you can retrieve the supported rendering APIs, check the features they support, activate the one you want/can use.

Here is a small example, to select the rendering API from a command-line option:

#define ASHES_VK_PROTOTYPES
#include <ashes/ashes.h>

AshPluginDescription * enumeratePlugins( uint32_t * pluginsCount )
{
	AshPluginDescription * result = NULL;
	ashEnumeratePluginsDescriptions( pluginsCount, NULL );

	if ( *pluginsCount )
	{
		result = malloc( ( *pluginsCount ) * sizeof( AshPluginDescription ) );
		ashEnumeratePluginsDescriptions( pluginsCount, result );
	}

	return result;
}

int selectPlugin( AshPluginDescription * plugins, uint32_t pluginsCount, char * option )
{
	int selectedPlugin = -1;

	if ( pluginsCount > 0 )
	{
		char name[17];

		for ( uint32_t i = 0; i < pluginsCount; ++i )
		{
			strncpy( name, "-", 16 );
			strncat( name, plugins[i].name, 16 );

			if ( strcmp( option, name ) == 0 )
			{
				selectedPlugin = i;
			}
		}
	}

	return selectedPlugin;
}

int main( int argc, char ** argv )
{
	uint32_t pluginsCount = 0u;
	int selectedPlugin = -1;
	AshPluginDescription * plugins = enumeratePlugins( &pluginsCount );

	for ( int i = 1; i < argc; ++i )
	{
		if ( selectedPlugin == -1 )
		{
			selectedPlugin = selectPlugin( plugins, pluginsCount, argv[i] );
		}
	}

	ashSelectPlugin( selectPlugin );

	// Now write classic Vulkan code.
	// ...
	//
}

Building Ashes from source

Ashes relies on CMake as project generator. The easiest way to build it is to use the presets already defined:

dev-msvc: Visual Studio build, you need to provide the necessary libraries.
dev-ninja-debug, dev-ninja-release]: Ninja build, you need to provide the necessary libraries.
dev-vcpkg-msvc: Visual Studio build, using vcpkg to fetch the dependencies.
dev-vcpkg-ninja-debug, dev-vcpkg-ninja-release]: Ninja build, using vcpkg to fetch the dependencies.

Contact

You can reach me on the Discord server dedicated to my projects: DragonJoker's Lair

Validation

Ashes is validated using Sascha Willems' Vulkan examples repository.
I've forked it, to be able to test the drivers.

Test applications

These applications are used to validate the basic functionalities of the ashespp library.

Sample applications

Sample apps to implement

Compute particle system.

These applications use the library in a more complex way, closer to what would be done within an engine.