2016年7月6日水曜日

Vulkan - インスタンスの生成と破棄

ようやくVulkanインスタンスを生成します.

VkApplicationInfoの初期化

Vulkanインスタンスを生成するために,構造体VkInstanceCreateInfoが必要です.
この構造体を初期化するために,構造体VkApplicationInfoを初期化する必要があります.

構造体VkApplicationInfoは,次のような構造になっています.

struct VkApplicationInfo {
    VkStructureType    sType;
    const void*        pNext;
    const char*        pApplicationName;
    uint32_t           applicationVersion;
    const char*        pEngineName;
    uint32_t           engineVersion;
    uint32_t           apiVersion;
};

sTypeには,VK_STRUCTURE_TYPE_APPLICATION_INFOを設定する必要があります.
pNextはnullptrを設定する必要があります.
apiVersionには,VK_API_VERSION_1_0を設定します.今のところ,他のバージョンを設定するとインスタンスが生成できない場合があります.
pApplicatoinName,applicationVersion,pEngineName,engineVersionは適当でも大丈夫そうですが,今後どうなるかは分かりません.

VkInstanceCreateInfoの初期化

VkApplicationInfoを初期化したら,VkInstanceCreateInfoを初期化します.VkInstanceCreateInfoは次のような構造になっています.

struct VkInstanceCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkInstanceCreateFlags       flags;
    const VkApplicationInfo*    pApplicationInfo;
    uint32_t                    enabledLayerCount;
    const char* const*          ppEnabledLayerNames;
    uint32_t                    enabledExtensionCount;
    const char* const*          ppEnabledExtensionNames;
};

sTypeには,VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFOを設定する必要があります.
pNextはnullptrを設定する必要があります.
flagsは今後のために予約されており,現時点では0を指定します.
pApplicationInfoには,前もって初期化しておいたVkApplicationInfoの変数へのポインタを設定します.
enabledLayerCountには有効にしたいレイヤーの数を,ppEnabledLayerNamesには有効にしたいレイヤー名へのポインタの配列を設定します.
enabledExtensionCount,ppEnabledExtensionNamesもレイヤーと同様に,有効にしたい拡張機能の数と名前へのポインタの配列を設定します.

Vulkanインスタンスの生成

VkInstanceCreateInfoが初期化できたら,次のようなvkCreateInstance()を呼び出してVulkanインスタンスを生成します.

VkResult vkCreateInstance(
    const VkInstanceCreateInfo * pCreateInfo,
    const VkAllocationCallbacks * pAllocator,
    VkInstance * pInstance
);

pCreateInfoには,初期化しておいたVkInstanceCreateInfoの変数へのポインタを渡します.
pAllocatorは,nullptrを指定します.適切な設定をすると,メモリ管理を制御できるのですが,今回は触れません.
pInstanceには,実際に生成されたVulkanインスタンスへのハンドルが設定されるので,VkInstanceの変数へのポインタを渡します.

Vulkanインスタンスの破棄

最後に,次のようなvkDestroyInstance()を呼び出してインスタンスを破棄して終了です.

void vkDestroyInstance(
    VkInstance * pInstance
    const VkAllocationCallbacks * pAllocator
);

実例

以下は,実際にVulkanインスタンスを生成して破棄するだけのコードです.本来は,それぞれのレイヤーがあるかどうか,拡張機能は利用できるかどうか,などを確認すべきですが,ここではそのあたりは省略しています.

#include <iostream>
#include <vector>
#include <vulkan/vulkan.h>

#pragma comment(lib, "vulkan-1")

using namespace std;

int main()
{
    // アプリケーション情報を初期化
    VkApplicationInfo applicationInfo {};
    applicationInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
    applicationInfo.pNext = nullptr;
    applicationInfo.pApplicationName = "";
    applicationInfo.applicationVersion = 0;
    applicationInfo.pEngineName = "";
    applicationInfo.engineVersion = 0;
    // VK_VERSION_1_0と間違えないこと
    applicationInfo.apiVersion = VK_API_VERSION_1_0;

    // APIの実引数をダンプしてくれるレイヤーを有効化しておく
    vector<const char *> layerNames {
        "VK_LAYER_LUNARG_api_dump"
    };
    // 今後必要になる拡張機能を有効にしておく
    vector<const char *> extensionNames {
        "VK_KHR_surface",
        "VK_KHR_win32_surface"
    };

    // インスタンス生成情報を初期化
    VkInstanceCreateInfo instanceCreateInfo {};
    instanceCreateInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
    instanceCreateInfo.pNext = nullptr;
    instanceCreateInfo.flags = 0;
    instanceCreateInfo.pApplicationInfo = &applicationInfo;
    instanceCreateInfo.enabledLayerCount = layerNames.size();
    instanceCreateInfo.ppEnabledLayerNames = layerNames.data();
    instanceCreateInfo.enabledExtensionCount = extensionNames.size();
    instanceCreateInfo.ppEnabledExtensionNames = extensionNames.data();

    // Vulkanインスタンスを生成
    VkInstance instance = VK_NULL_HANDLE;
    VkResult result = vkCreateInstance(&instanceCreateInfo, nullptr, &instance);
    if(result != VK_SUCCESS)
    {
        cerr << "Vulkanインスタンスの生成に失敗" << endl;
        return -1;
    }
    cout << "Vulkanインスタンスの生成に成功" << endl;

    vkDestroyInstance(instance, nullptr);
}

サンプルコードは,ryutorion/LearningVulkan (GitHubリポジトリ)の003_CreateInstanceにもあります.

Vulkan - インスタンス拡張機能の列挙

拡張機能とは

レイヤーの列挙,でも書いたように,レイヤーはVulkan APIによって発行されるコマンドに割り込みをかけるものです.

一方,拡張機能はVulkanのコマンドなどを追加します.

インスタンス拡張機能の列挙

拡張機能を列挙するための手順は,レイヤーを列挙する際の手順に似ています.インスタンス拡張機能の場合,次のようなvkEnumerateInstanceExtensionProperties()を呼び出します.

VkResult vkEnumerateInstanceExtensionProperties(
    const char * pLayerName,
    uint32_t * pPropertyCount,
    VkExtensionProperties * pProperties
);

仮引数の名前を見ると分かるように,インスタンス拡張機能はレイヤーに紐付いています.ただし,pLayerNameにnullptrを指定することも可能で,その場合はデフォルトで利用可能なインスタンス拡張が列挙されます.

インスタンス拡張機能の情報は,次のような構造体に保存されます.

struct VkExtensionProperties {
    char        extensionName[VK_MAX_EXTENSION_NAME_SIZE];
    uint32_t    specVersion;
};

以下の例では,利用可能なレイヤー名を全て取得し,更にnullptrを追加した上で,インスタンス拡張を列挙して,その情報をダンプしています.

#include <iostream>
#include <vector>
#include <vulkan/vulkan.h>

#pragma comment(lib, "vulkan-1")

using namespace std;

class version
{
public:
    version(uint32_t value) : mValue(value) {}

    uint32_t value() const { return mValue; }
    uint32_t major() const { return VK_VERSION_MAJOR(mValue); }
    uint32_t minor() const { return VK_VERSION_MINOR(mValue); }
    uint32_t patch() const { return VK_VERSION_PATCH(mValue); }

private:
    uint32_t mValue;
};

std::ostream & operator<<(std::ostream & out, const version & v)
{
    out << v.major() << "." << v.minor() << "." << v.patch();
    return out;
}

int main()
{
    VkResult result = VK_SUCCESS;
    vector<VkLayerProperties> layers {};
    do {
        uint32_t count = 0;
        result = vkEnumerateInstanceLayerProperties(&count, nullptr);
        if(result != VK_SUCCESS)
        {
            break;
        }

        layers.resize(count);
        result = vkEnumerateInstanceLayerProperties(&count, layers.data());
    } while(result == VK_INCOMPLETE);

    // レイヤー名の配列を生成
    vector<const char *> layerNames(layers.size() + 1);
    for(auto i = 0; i < layers.size(); ++i)
    {
        layerNames[i] = layers[i].layerName;
    }
    layerNames[layers.size()] = nullptr;

    for(auto layerName : layerNames)
    {
        cout << (layerName ? layerName : "No Layer Name") << endl;

        // レイヤーに対応する拡張の取得
        vector<VkExtensionProperties> extensions;
        do {
            uint32_t count = 0;
            result = vkEnumerateInstanceExtensionProperties(layerName, &count, nullptr);
            if(result != VK_SUCCESS)
            {
                break;
            }

            extensions.resize(count);
            result = vkEnumerateInstanceExtensionProperties(layerName, &count, extensions.data());
        } while(result == VK_INCOMPLETE);

        for(auto & extension : extensions)
        {
            cout << "\tExtension Name        : " << extension.extensionName << endl;
            cout << "\tSpecification Version : " << version(extension.specVersion) << endl;
            cout << endl;
        }
    }
}

GitHubのリポジトリryutorion/LearningVulkanの002_EnumerateInstanceExtensionsに実際のコードがあります.

2016年7月5日火曜日

Vulkan - レイヤーの列挙

最近ブログ書いてなかったので,Vulkanについて調べたり試したことを書いていこうかと思います.

環境

OS Windows 10 Pro
GPU NVIDIA GeForce GTX 860M (ドライバー 368.22)
Vulkan SDKバージョン 1.0.17.0

レイヤーとは

Vulkanのインスタンス,またはインスタンスを介して生成されたオブジェクトに対して発行されるVulkanのコマンドに対して,割り込みをかけるための機能です.

例えば,VK_LAYER_LUNARG_api_dumpというレイヤーは,VulkanのAPIを実行した際に,実引数をダンプしてくれます.

レイヤーは,Vulkanのインスタンスを生成する際に指定することで有効になります.

レイヤーの列挙

利用可能なレイヤーの一覧を取得するには,次のvkEnumerateInstanceLayerProperties()を利用します.
VkResult vkEnumerateInstanceLayerProperties(
    uint32_t * pPropertyCount,
    VkLayerProperties * pProperties
);

まず,pPropertyCountに変数へのポインタ,pPropertiesにnullptrを渡すことでレイヤーの数を取得します.
uint32_t count;
vkEnumerateInstanceLayerProperties(&count, nullptr);

次に,必要なバッファを用意して各レイヤーの情報を取得します.ここでは,vectorクラスを利用しています.
vector<VkLayerProperties> layers {};
VkResult result = vkEnumerateInstanceLayerProperties(&count, layers.data());

実際に各レイヤーの情報を取得する際に,レイヤーの数を取得してから情報を取得するまでの間に,レイヤーが追加される場合があります.そんな珍しい状況が発生した場合,vkEnumerateInstanceLayerProperties()はVK_INCOMPLETEを返します.VK_INCOMPLETEが返された場合,レイヤー数の取得からやり直します.

取得されたレイヤーの情報は,次のような構造体に格納されます.

struct VkLayerProperties {
    char        layerName[VK_MAX_EXTENSION_NAME_SIZE];
    uint32_t    specVersion;
    uint32_t    implementationVersion;
    char        description[VK_MAX_DESCRIPTION_SIZE];
};

サンプルコード

以下のコードは,vkEnumerateInstanceLayerProperties()を使って,全てのレイヤー情報をダンプするものです.Vulkanのバージョン情報を分かりやすい形で表示するために,versionクラスを導入しています.

#include <iostream>
#include <vector>
#include <vulkan/vulkan.h>

#pragma comment(lib, "vulkan-1")

using namespace std;

class version
{
public:
    version(uint32_t value) : mValue(value) {}

    //! 値を返す
    uint32_t value() const { return mValue; }

    //! メジャーバージョンを返す
    uint32_t major() const { return VK_VERSION_MAJOR(mValue); }

    //! マイナーバージョンを返す
    uint32_t minor() const { return VK_VERSION_MINOR(mValue); }

    //! パッチバージョンを返す
    uint32_t patch() const { return VK_VERSION_PATCH(mValue); }

private:
    uint32_t mValue;
};

std::ostream & operator<<(std::ostream & out, const version & v)
{
    out << v.major() << "." << v.minor() << "." << v.patch();
    return out;
}

int main()
{
    VkResult result = VK_SUCCESS;
    vector layers {};
    do {
        // レイヤー数を取得
        uint32_t count = 0;
        result = vkEnumerateInstanceLayerProperties(&count, nullptr);
        if(result != VK_SUCCESS)
        {
            break;
        }

        // 各レイヤーのプロパティを取得
        layers.resize(count);
        result = vkEnumerateInstanceLayerProperties(&count, layers.data());

        // 全てのレイヤーを取得していない場合,やり直す
    } while(result == VK_INCOMPLETE);

    // 各レイヤーのプロパティを出力する
    for(auto layer : layers)
    {
        cout << "Layer Name             : " << layer.layerName << endl;
        cout << "Specification Version  : " << version(layer.specVersion) << endl;
        cout << "Implementation Version : " << version(layer.implementationVersion) << endl;
        cout << "Description            : " << layer.description << endl;
        cout << endl;
    }
}

インスタンスを生成する際には上記の手順で取得したレイヤーを指定すれば良いのですが,まだ問題が起きるレイヤーがあります.しばらくは,レイヤーの使用に問題が無いか確認してから,本番環境で有効化するか検討した方が良いでしょう.

サンプルコードは,ryutorion/LearningVulkan (GitHubリポジトリ)の001_EnumerateInstanceLayerにもあります.