среда, 24 февраля 2016 г.

Vulkan API, Initialization

Продолжаю переводить спецификацию, перевод предыдущего раздела можно посмотреть здесь: http://vbomesh.blogspot.com/2016/02/vulkan-api-fundamentals.html
В этот раз перевод коснется раздела Инициализации Вулкана.


Прежде чем начать использовать Вулкан приложение должно его инициализировать через загрузку его команд и создание инстанса объекта VkInstance.
Указатели на все команды Вулкана могут быть получены через команду:
PFN_vkVoidFunction
vkGetInstanceProcAddr(VkInstance instance, const char * pName);
• instance -  инстанс с которым будет совместим указатель на функцию.
• pName - имя команды, которую мы хотим получить.


При этом:
instance не должен быть равен NULL, он должен быть валидным хэндлом типа VkInstance.
pName -  null-terminated string


Если instance равен NULL, то pName должно быть одним из: vkEnumerateInstanceExtensionProperties, vkEnumerateInstanceLayerProperties или vkCreateInstance.


Получение же самого vkGetInstanceProcAddr зависит от платформы и он обычно предоставляется лоадером. Указатели на функции, которые не оперируют с конкретным инстансом могут быть получены аналогично через vkGetInstanceProcAddr, при этом instance должен быть равен NULL. Таким образом могут быть получены следующие команды:
• vkEnumerateInstanceExtensionProperties
• vkEnumerateInstanceLayerProperties
• vkCreateInstance


В случае ошибки (если pName не является именем команды Вулкана или одного из расширений) то функция vkGetInstanceProcAddr вернет NULL.


В системе с несколькими реализациями Вулкана и несколькими устройствами это может вызывать некоторый оверхед, чтоб избежать этого можно получить указатель на команду конкретного устройства.  Это реализуется с помощью следующей команды:
PFN_vkVoidFunction
vkGetDeviceProcAddr( VkDevice device, const char * pName);
• device - логическое устройство, которое предоставляет указатель на функцию.
• pName - имя команды Вулкана, у которой первый параметр один из
– VkDevice
– VkQueue
– VkCommandBuffer
В случае ошибки (если pName не является именем команды Вулкана или одного из расширений) то функция vkGetDeviceProcAddr вернет NULL.


Instances


В Вулкане нет понятия глобальных стэйтов, все определенные для приложения стэйты хранятся в объекте VkInstance, создание этого объекта инициализирует библиотеку Вулкана. Чтоб создать инстанс выполните:
VkResult vkCreateInstance(
const VkInstanceCreateInfo * pCreateInfo,
const VkAllocationCallbacks * pAllocator,
VkInstance * pInstance);
• pCreateInfo - указатель на структуру VkInstanceCreateInfo, которая контролирует создание инстанса.
• pAllocator - контролирует выделение памяти хостом, если не NULL то должен быть указателем на валидную структуру VkAllocationCallbacks.
• pInstance - сюда возвращается указатель на созданный инстанс.


Возвращаемые значения:
Успешно:
• VK_SUCCESS
Ошибка:
• VK_ERROR_OUT_OF_HOST_MEMORY
• VK_ERROR_OUT_OF_DEVICE_MEMORY
• VK_ERROR_INITIALIZATION_FAILED
• VK_ERROR_LAYER_NOT_PRESENT
• VK_ERROR_EXTENSION_NOT_PRESENT
• VK_ERROR_INCOMPATIBLE_DRIVER


Определение структуры VkInstanceCreateInfo:
typedef 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;
} VkInstanceCreateInfo;

• sType - тип данной структуры.
• pNext  - NULL или указатель дополнительные данные.
• flags  - зарезервированно.
• pApplicationInfo - NULL или указатель на инстанс VkApplicationInfo. Если не NULL то  эта информация помогает определить класс поведения приложения
• enabledLayerCount - количество глобальных слоев для активации.
• ppEnabledLayerNames - указатель на массив из enabledLayerCount null-terminated UTF-8 строк, содержащих имена слоев для активации.
• enabledExtensionCount - количество глобальных расширений для активации.
• ppEnabledExtensionNames - указатель на массив из enabledExtensionCount null-terminated UTF-8 строк, содержащих имена активируемых расширений.
Правильное использование данной структуры:
• sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO
• pNext = NULL
• flags = 0
• pApplicationInfo = NULL или указатель на валидную структуру VkApplicationInfo.
Некоторые драйвера не работают если указать pApplicationInfo = NULL, так что лучше перестраховаться и передать туда заполненную структуру
• enabledLayerCount - если не 0, то ppEnabledLayerNames должно указывать на массив строк
• enabledExtensionCount - если не 0, то ppEnabledExtensionNames должно указывать на массив строк
• Любой из элементов ppEnabledLayerNames должен быть именем существующего в системе слоя, совпадающего со строкой, возвращаемой в структуре VkLayerProperties функцией vkEnumerateInstanceLayerProperties.
• Любой из элементов ppEnabledExtensionNames должен быть именем существующего в системе расширения, совпадающего со строкой, возвращаемой в структуре VkExtensionProperties функцией vkEnumerateInstanceExtensionProperties.
• Если расширение указанное в ppEnabledExtensionNames представлено как часть слоя тогда, для использования, и слой и расширение должны быть активированы.


vkCreateInstance создает инстанс, активирует и инициализирует глобальные слои и расширения, запрашиваемые приложением. Если расширение предоставляется слоем, то они оба должны быть определены в момент вызова vkCreateInstance.


Поле pApplicationInfo структуры VkInstanceCreateInfo может указывать на структуру
VkApplicationInfo, которая объявлена как:

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


• sType - тип структуры, должен быть VK_STRUCTURE_TYPE_APPLICATION_INFO.
• pNext  - должен быть NULL.
• pApplicationName - указатель на UTF-8 строку содержащую имя приложения.
• applicationVersion - беззнаковое целое, содержит номер версии приложения.
• pEngineName - указатель на UTF-8 строку, содержащую имя движка, использованного для создания приложения.
• engineVersion - беззнаковое целое, содержит номер версии движка.
• apiVersion - версия Vulkan API, на которой предполагается запускать приложение. Если версия равна 0 - имплементация должна игнорить версию API, иначе, если исплиментация не поддерживает данную версию она должна вернуть VK_ERROR_INCOMPATIBLE_DRIVER.
Удаление инстанса производится функцией:
vkDestroyInstance(VkInstance instance, const VkAllocationCallbacks * pAllocator);
• instance - хэндл инстанса (VkInstance) для удаления.
• pAllocator - аллокатор, если не NULL то должен быть указателем на структуру VkAllocationCallbacks.


Все дочерние объекты созданные через instance должны быть удалены до удаления самого инстанса.

Доступ к инстансу на стороне хоста должен иметь внешнюю синхронизацию.

Комментариев нет:

Отправить комментарий