Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / vulkan-validation-layers / 6911e8c6f7fd0de4a6c0591462a3da3c0bf2b4a8 / . / include / vulkan / vk_layer.h
blob: 133b87379538bee18478ec89f1f4e664238f06c6 [file] [log] [blame]
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]1/* Need to define dispatch table
2 * Core struct can then have ptr to dispatch table at the top
3 * Along with object ptrs for current and next OBJ
4 */
5#pragma once
6
David Pinedo329ca9e2015-11-06 12:54:48 -0700[diff] [blame]7#include "vulkan/vulkan.h"
David Pinedoa31fe0b2015-11-24 09:00:24 -0700[diff] [blame]8#include "vulkan/vk_lunarg_debug_report.h"
9#include "vulkan/vk_lunarg_debug_marker.h"
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]10#if defined(__GNUC__) && __GNUC__ >= 4
11# define VK_LAYER_EXPORT __attribute__((visibility("default")))
12#elif defined(__SUNPRO_C) && (__SUNPRO_C >= 0x590)
13# define VK_LAYER_EXPORT __attribute__((visibility("default")))
14#else
15# define VK_LAYER_EXPORT
16#endif
17
Jon Ashburn429e19f2015-11-17 15:31:02 -0700[diff] [blame]18typedef void * (VKAPI_PTR *PFN_vkGPA)(void* obj, const char * pName);
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]19typedef struct VkBaseLayerObject_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]20{
Jon Ashburn79b78ac2015-05-05 14:22:52 -0600[diff] [blame]21 PFN_vkGPA pGPA;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]22 void* nextObject;
23 void* baseObject;
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]24} VkBaseLayerObject;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]25
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]26typedef struct VkLayerDispatchTable_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]27{
Jon Ashburn1245cec2015-05-18 13:20:15 -0600[diff] [blame]28 PFN_vkGetDeviceProcAddr GetDeviceProcAddr;
Courtney Goeltzenleuchterbe637992015-06-25 18:01:43 -0600[diff] [blame]29 PFN_vkCreateDevice CreateDevice;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]30 PFN_vkDestroyDevice DestroyDevice;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]31 PFN_vkGetDeviceQueue GetDeviceQueue;
32 PFN_vkQueueSubmit QueueSubmit;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]33 PFN_vkQueueWaitIdle QueueWaitIdle;
34 PFN_vkDeviceWaitIdle DeviceWaitIdle;
Chia-I Wu1f851912015-10-27 18:04:07 +0800[diff] [blame]35 PFN_vkAllocateMemory AllocateMemory;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]36 PFN_vkFreeMemory FreeMemory;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]37 PFN_vkMapMemory MapMemory;
38 PFN_vkUnmapMemory UnmapMemory;
Courtney Goeltzenleuchtera569a502015-04-29 17:16:21 -0600[diff] [blame]39 PFN_vkFlushMappedMemoryRanges FlushMappedMemoryRanges;
40 PFN_vkInvalidateMappedMemoryRanges InvalidateMappedMemoryRanges;
Courtney Goeltzenleuchterd040c5c2015-07-09 21:57:28 -0600[diff] [blame]41 PFN_vkGetDeviceMemoryCommitment GetDeviceMemoryCommitment;
Mark Lobodzinski83d4e6a2015-07-03 15:58:09 -0600[diff] [blame]42 PFN_vkGetImageSparseMemoryRequirements GetImageSparseMemoryRequirements;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]43 PFN_vkGetImageMemoryRequirements GetImageMemoryRequirements;
44 PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
45 PFN_vkBindImageMemory BindImageMemory;
46 PFN_vkBindBufferMemory BindBufferMemory;
Chia-I Wu06809d52015-10-26 16:55:27 +0800[diff] [blame]47 PFN_vkQueueBindSparse QueueBindSparse;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]48 PFN_vkCreateFence CreateFence;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]49 PFN_vkDestroyFence DestroyFence;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]50 PFN_vkGetFenceStatus GetFenceStatus;
51 PFN_vkResetFences ResetFences;
52 PFN_vkWaitForFences WaitForFences;
53 PFN_vkCreateSemaphore CreateSemaphore;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]54 PFN_vkDestroySemaphore DestroySemaphore;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]55 PFN_vkCreateEvent CreateEvent;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]56 PFN_vkDestroyEvent DestroyEvent;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]57 PFN_vkGetEventStatus GetEventStatus;
58 PFN_vkSetEvent SetEvent;
59 PFN_vkResetEvent ResetEvent;
60 PFN_vkCreateQueryPool CreateQueryPool;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]61 PFN_vkDestroyQueryPool DestroyQueryPool;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]62 PFN_vkGetQueryPoolResults GetQueryPoolResults;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]63 PFN_vkCreateBuffer CreateBuffer;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]64 PFN_vkDestroyBuffer DestroyBuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]65 PFN_vkCreateBufferView CreateBufferView;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]66 PFN_vkDestroyBufferView DestroyBufferView;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]67 PFN_vkCreateImage CreateImage;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]68 PFN_vkDestroyImage DestroyImage;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]69 PFN_vkGetImageSubresourceLayout GetImageSubresourceLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]70 PFN_vkCreateImageView CreateImageView;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]71 PFN_vkDestroyImageView DestroyImageView;
Courtney Goeltzenleuchter0b29b0d2015-06-24 18:24:19 -0600[diff] [blame]72 PFN_vkCreateShaderModule CreateShaderModule;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]73 PFN_vkDestroyShaderModule DestroyShaderModule;
Jon Ashburn0d60d272015-07-09 15:02:25 -0600[diff] [blame]74 PFN_vkCreatePipelineCache CreatePipelineCache;
75 PFN_vkDestroyPipelineCache DestroyPipelineCache;
Jon Ashburn0d60d272015-07-09 15:02:25 -0600[diff] [blame]76 PFN_vkGetPipelineCacheData GetPipelineCacheData;
77 PFN_vkMergePipelineCaches MergePipelineCaches;
78 PFN_vkCreateGraphicsPipelines CreateGraphicsPipelines;
79 PFN_vkCreateComputePipelines CreateComputePipelines;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]80 PFN_vkDestroyPipeline DestroyPipeline;
Mark Lobodzinski556f7212015-04-17 14:11:39 -0500[diff] [blame]81 PFN_vkCreatePipelineLayout CreatePipelineLayout;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]82 PFN_vkDestroyPipelineLayout DestroyPipelineLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]83 PFN_vkCreateSampler CreateSampler;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]84 PFN_vkDestroySampler DestroySampler;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]85 PFN_vkCreateDescriptorSetLayout CreateDescriptorSetLayout;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]86 PFN_vkDestroyDescriptorSetLayout DestroyDescriptorSetLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]87 PFN_vkCreateDescriptorPool CreateDescriptorPool;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]88 PFN_vkDestroyDescriptorPool DestroyDescriptorPool;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]89 PFN_vkResetDescriptorPool ResetDescriptorPool;
Chia-I Wu1f851912015-10-27 18:04:07 +0800[diff] [blame]90 PFN_vkAllocateDescriptorSets AllocateDescriptorSets;
Tony Barbourb857d312015-07-10 10:50:45 -0600[diff] [blame]91 PFN_vkFreeDescriptorSets FreeDescriptorSets;
Chia-I Wu8cd8ecd2015-05-25 16:27:55 +0800[diff] [blame]92 PFN_vkUpdateDescriptorSets UpdateDescriptorSets;
Jon Ashburna25465c2015-07-23 18:48:20 -0600[diff] [blame]93 PFN_vkCreateFramebuffer CreateFramebuffer;
94 PFN_vkDestroyFramebuffer DestroyFramebuffer;
95 PFN_vkCreateRenderPass CreateRenderPass;
96 PFN_vkDestroyRenderPass DestroyRenderPass;
97 PFN_vkGetRenderAreaGranularity GetRenderAreaGranularity;
Cody Northropf02f9f82015-07-09 18:08:05 -0600[diff] [blame]98 PFN_vkCreateCommandPool CreateCommandPool;
99 PFN_vkDestroyCommandPool DestroyCommandPool;
100 PFN_vkResetCommandPool ResetCommandPool;
Chia-I Wu1f851912015-10-27 18:04:07 +0800[diff] [blame]101 PFN_vkAllocateCommandBuffers AllocateCommandBuffers;
Courtney Goeltzenleuchter831c1832015-10-23 14:21:05 -0600[diff] [blame]102 PFN_vkFreeCommandBuffers FreeCommandBuffers;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]103 PFN_vkBeginCommandBuffer BeginCommandBuffer;
104 PFN_vkEndCommandBuffer EndCommandBuffer;
105 PFN_vkResetCommandBuffer ResetCommandBuffer;
106 PFN_vkCmdBindPipeline CmdBindPipeline;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]107 PFN_vkCmdBindDescriptorSets CmdBindDescriptorSets;
Courtney Goeltzenleuchter46962942015-04-16 13:38:46 -0600[diff] [blame]108 PFN_vkCmdBindVertexBuffers CmdBindVertexBuffers;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]109 PFN_vkCmdBindIndexBuffer CmdBindIndexBuffer;
Courtney Goeltzenleuchter09772bb2015-09-17 15:06:17 -0600[diff] [blame]110 PFN_vkCmdSetViewport CmdSetViewport;
Courtney Goeltzenleuchter932cdb52015-09-21 11:44:06 -0600[diff] [blame]111 PFN_vkCmdSetScissor CmdSetScissor;
Courtney Goeltzenleuchter09772bb2015-09-17 15:06:17 -0600[diff] [blame]112 PFN_vkCmdSetLineWidth CmdSetLineWidth;
113 PFN_vkCmdSetDepthBias CmdSetDepthBias;
114 PFN_vkCmdSetBlendConstants CmdSetBlendConstants;
115 PFN_vkCmdSetDepthBounds CmdSetDepthBounds;
116 PFN_vkCmdSetStencilCompareMask CmdSetStencilCompareMask;
117 PFN_vkCmdSetStencilWriteMask CmdSetStencilWriteMask;
118 PFN_vkCmdSetStencilReference CmdSetStencilReference;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]119 PFN_vkCmdDraw CmdDraw;
120 PFN_vkCmdDrawIndexed CmdDrawIndexed;
121 PFN_vkCmdDrawIndirect CmdDrawIndirect;
122 PFN_vkCmdDrawIndexedIndirect CmdDrawIndexedIndirect;
123 PFN_vkCmdDispatch CmdDispatch;
124 PFN_vkCmdDispatchIndirect CmdDispatchIndirect;
125 PFN_vkCmdCopyBuffer CmdCopyBuffer;
126 PFN_vkCmdCopyImage CmdCopyImage;
127 PFN_vkCmdBlitImage CmdBlitImage;
128 PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
129 PFN_vkCmdCopyImageToBuffer CmdCopyImageToBuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]130 PFN_vkCmdUpdateBuffer CmdUpdateBuffer;
131 PFN_vkCmdFillBuffer CmdFillBuffer;
132 PFN_vkCmdClearColorImage CmdClearColorImage;
Chris Forbes2951d7d2015-06-22 17:21:59 +1200[diff] [blame]133 PFN_vkCmdClearDepthStencilImage CmdClearDepthStencilImage;
Courtney Goeltzenleuchter9feb0732015-10-15 16:51:05 -0600[diff] [blame]134 PFN_vkCmdClearAttachments CmdClearAttachments;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]135 PFN_vkCmdResolveImage CmdResolveImage;
136 PFN_vkCmdSetEvent CmdSetEvent;
137 PFN_vkCmdResetEvent CmdResetEvent;
138 PFN_vkCmdWaitEvents CmdWaitEvents;
139 PFN_vkCmdPipelineBarrier CmdPipelineBarrier;
140 PFN_vkCmdBeginQuery CmdBeginQuery;
141 PFN_vkCmdEndQuery CmdEndQuery;
142 PFN_vkCmdResetQueryPool CmdResetQueryPool;
143 PFN_vkCmdWriteTimestamp CmdWriteTimestamp;
Courtney Goeltzenleuchter98049062015-04-15 18:21:13 -0600[diff] [blame]144 PFN_vkCmdCopyQueryPoolResults CmdCopyQueryPoolResults;
Jon Ashburna25465c2015-07-23 18:48:20 -0600[diff] [blame]145 PFN_vkCmdPushConstants CmdPushConstants;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]146 PFN_vkCmdBeginRenderPass CmdBeginRenderPass;
Chia-I Wuc278df82015-07-07 11:50:03 +0800[diff] [blame]147 PFN_vkCmdNextSubpass CmdNextSubpass;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]148 PFN_vkCmdEndRenderPass CmdEndRenderPass;
Chia-I Wu88eaa3b2015-06-26 15:34:39 +0800[diff] [blame]149 PFN_vkCmdExecuteCommands CmdExecuteCommands;
Ian Elliott338dedb2015-08-21 15:09:33 -0600[diff] [blame]150 PFN_vkCreateSwapchainKHR CreateSwapchainKHR;
151 PFN_vkDestroySwapchainKHR DestroySwapchainKHR;
152 PFN_vkGetSwapchainImagesKHR GetSwapchainImagesKHR;
153 PFN_vkAcquireNextImageKHR AcquireNextImageKHR;
154 PFN_vkQueuePresentKHR QueuePresentKHR;
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]155} VkLayerDispatchTable;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]156
Jon Ashburn9a9bb642015-05-04 16:27:53 -0600[diff] [blame]157typedef struct VkLayerInstanceDispatchTable_
158{
159 PFN_vkGetInstanceProcAddr GetInstanceProcAddr;
Jon Ashburn52c1d732015-05-12 17:23:55 -0600[diff] [blame]160 PFN_vkCreateInstance CreateInstance;
Jon Ashburn9a9bb642015-05-04 16:27:53 -0600[diff] [blame]161 PFN_vkDestroyInstance DestroyInstance;
162 PFN_vkEnumeratePhysicalDevices EnumeratePhysicalDevices;
Chris Forbesd7576302015-06-21 22:55:02 +1200[diff] [blame]163 PFN_vkGetPhysicalDeviceFeatures GetPhysicalDeviceFeatures;
Jon Ashburna25465c2015-07-23 18:48:20 -0600[diff] [blame]164 PFN_vkGetPhysicalDeviceImageFormatProperties GetPhysicalDeviceImageFormatProperties;
Courtney Goeltzenleuchter4da96aa2015-07-12 12:52:09 -0600[diff] [blame]165 PFN_vkGetPhysicalDeviceFormatProperties GetPhysicalDeviceFormatProperties;
Mark Lobodzinski83d4e6a2015-07-03 15:58:09 -0600[diff] [blame]166 PFN_vkGetPhysicalDeviceSparseImageFormatProperties GetPhysicalDeviceSparseImageFormatProperties;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]167 PFN_vkGetPhysicalDeviceProperties GetPhysicalDeviceProperties;
Cody Northropef72e2a2015-08-03 17:04:53 -0600[diff] [blame]168 PFN_vkGetPhysicalDeviceQueueFamilyProperties GetPhysicalDeviceQueueFamilyProperties;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]169 PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties;
Courtney Goeltzenleuchter74c4ce92015-09-14 17:22:16 -0600[diff] [blame]170 PFN_vkEnumerateDeviceExtensionProperties EnumerateDeviceExtensionProperties;
171 PFN_vkEnumerateDeviceLayerProperties EnumerateDeviceLayerProperties;
Jon Ashburn6911e8c2015-11-23 18:55:15 -0700[diff] [blame^]172 PFN_vkDestroySurfaceKHR DestroySurfaceKHR;
Ian Elliott338dedb2015-08-21 15:09:33 -0600[diff] [blame]173 PFN_vkGetPhysicalDeviceSurfaceSupportKHR GetPhysicalDeviceSurfaceSupportKHR;
Ian Elliottbb03f402015-11-18 15:20:45 -0700[diff] [blame]174 PFN_vkGetPhysicalDeviceSurfaceCapabilitiesKHR GetPhysicalDeviceSurfaceCapabilitiesKHR;
175 PFN_vkGetPhysicalDeviceSurfaceFormatsKHR GetPhysicalDeviceSurfaceFormatsKHR;
176 PFN_vkGetPhysicalDeviceSurfacePresentModesKHR GetPhysicalDeviceSurfacePresentModesKHR;
Ian Elliott40c4a1f2015-11-23 10:17:23 -0700[diff] [blame]177#ifdef VK_USE_PLATFORM_MIR_KHR
178 PFN_vkCreateMirSurfaceKHR CreateMirSurfaceKHR;
179#endif
180#ifdef VK_USE_PLATFORM_WAYLAND_KHR
181 PFN_vkCreateWaylandSurfaceKHR CreateWaylandSurfaceKHR;
182#endif
183#ifdef VK_USE_PLATFORM_WIN32_KHR
184 PFN_vkCreateWin32SurfaceKHR CreateWin32SurfaceKHR;
185#endif
186#ifdef VK_USE_PLATFORM_XCB_KHR
187 PFN_vkCreateXcbSurfaceKHR CreateXcbSurfaceKHR;
188#endif
189#ifdef VK_USE_PLATFORM_XLIB_KHR
190 PFN_vkCreateXlibSurfaceKHR CreateXlibSurfaceKHR;
191#endif
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]192 PFN_vkDbgCreateMsgCallback DbgCreateMsgCallback;
193 PFN_vkDbgDestroyMsgCallback DbgDestroyMsgCallback;
Jon Ashburn9a9bb642015-05-04 16:27:53 -0600[diff] [blame]194} VkLayerInstanceDispatchTable;
195
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]196// LL node for tree of dbg callback functions
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]197typedef struct VkLayerDbgFunctionNode_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]198{
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]199 VkDbgMsgCallback msgCallback;
200 PFN_vkDbgMsgCallback pfnMsgCallback;
201 VkFlags msgFlags;
202 const void *pUserData;
203 struct VkLayerDbgFunctionNode_ *pNext;
204} VkLayerDbgFunctionNode;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]205
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]206typedef enum VkLayerDbgAction_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]207{
208 VK_DBG_LAYER_ACTION_IGNORE = 0x0,
209 VK_DBG_LAYER_ACTION_CALLBACK = 0x1,
210 VK_DBG_LAYER_ACTION_LOG_MSG = 0x2,
Courtney Goeltzenleuchterb94f0512015-10-05 14:41:34 -0600[diff] [blame]211 VK_DBG_LAYER_ACTION_BREAK = 0x4,
212 VK_DBG_LAYER_ACTION_DEBUG_OUTPUT = 0x8,
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]213} VkLayerDbgAction;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]214
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]215// ------------------------------------------------------------------------------------------------
216// API functions