Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / vulkan-validation-layers / d040c5c25acbea9cacfa90e346fe3a6095a15135 / . / include / vk_layer.h
blob: 6d1945bfa5edcd5f4e8873afab90534ae4c4f83a [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
7#include "vulkan.h"
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]8#include "vk_debug_report_lunarg.h"
9#include "vk_debug_marker_lunarg.h"
10#include "vk_wsi_lunarg.h"
Chia-I Wu5b66aa52015-04-16 22:02:10 +0800[diff] [blame]11#include "vk_wsi_lunarg.h"
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]12#if defined(__GNUC__) && __GNUC__ >= 4
13# define VK_LAYER_EXPORT __attribute__((visibility("default")))
14#elif defined(__SUNPRO_C) && (__SUNPRO_C >= 0x590)
15# define VK_LAYER_EXPORT __attribute__((visibility("default")))
16#else
17# define VK_LAYER_EXPORT
18#endif
19
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]20typedef void * (*PFN_vkGPA)(void* obj, const char * pName);
21
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]22typedef struct VkBaseLayerObject_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]23{
Jon Ashburn79b78ac2015-05-05 14:22:52 -0600[diff] [blame]24 PFN_vkGPA pGPA;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]25 void* nextObject;
26 void* baseObject;
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]27} VkBaseLayerObject;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]28
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]29typedef struct VkLayerDispatchTable_
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]30{
Jon Ashburn1245cec2015-05-18 13:20:15 -0600[diff] [blame]31 PFN_vkGetDeviceProcAddr GetDeviceProcAddr;
Courtney Goeltzenleuchterbe637992015-06-25 18:01:43 -0600[diff] [blame]32 PFN_vkCreateDevice CreateDevice;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]33 PFN_vkDestroyDevice DestroyDevice;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]34 PFN_vkGetDeviceQueue GetDeviceQueue;
35 PFN_vkQueueSubmit QueueSubmit;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]36 PFN_vkQueueWaitIdle QueueWaitIdle;
37 PFN_vkDeviceWaitIdle DeviceWaitIdle;
38 PFN_vkAllocMemory AllocMemory;
39 PFN_vkFreeMemory FreeMemory;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]40 PFN_vkMapMemory MapMemory;
41 PFN_vkUnmapMemory UnmapMemory;
Courtney Goeltzenleuchtera569a502015-04-29 17:16:21 -0600[diff] [blame]42 PFN_vkFlushMappedMemoryRanges FlushMappedMemoryRanges;
43 PFN_vkInvalidateMappedMemoryRanges InvalidateMappedMemoryRanges;
Courtney Goeltzenleuchterd040c5c2015-07-09 21:57:28 -0600[diff] [blame^]44 PFN_vkGetDeviceMemoryCommitment GetDeviceMemoryCommitment;
Mark Lobodzinski83d4e6a2015-07-03 15:58:09 -0600[diff] [blame]45 PFN_vkGetImageSparseMemoryRequirements GetImageSparseMemoryRequirements;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]46 PFN_vkGetImageMemoryRequirements GetImageMemoryRequirements;
47 PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
48 PFN_vkBindImageMemory BindImageMemory;
49 PFN_vkBindBufferMemory BindBufferMemory;
Mark Lobodzinskifb9f5642015-05-11 17:21:15 -0500[diff] [blame]50 PFN_vkQueueBindSparseBufferMemory QueueBindSparseBufferMemory;
Mark Lobodzinski83d4e6a2015-07-03 15:58:09 -0600[diff] [blame]51 PFN_vkQueueBindSparseImageOpaqueMemory QueueBindSparseImageOpaqueMemory;
Mark Lobodzinskifb9f5642015-05-11 17:21:15 -0500[diff] [blame]52 PFN_vkQueueBindSparseImageMemory QueueBindSparseImageMemory;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]53 PFN_vkCreateFence CreateFence;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]54 PFN_vkDestroyFence DestroyFence;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]55 PFN_vkGetFenceStatus GetFenceStatus;
56 PFN_vkResetFences ResetFences;
57 PFN_vkWaitForFences WaitForFences;
58 PFN_vkCreateSemaphore CreateSemaphore;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]59 PFN_vkDestroySemaphore DestroySemaphore;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]60 PFN_vkQueueSignalSemaphore QueueSignalSemaphore;
61 PFN_vkQueueWaitSemaphore QueueWaitSemaphore;
62 PFN_vkCreateEvent CreateEvent;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]63 PFN_vkDestroyEvent DestroyEvent;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]64 PFN_vkGetEventStatus GetEventStatus;
65 PFN_vkSetEvent SetEvent;
66 PFN_vkResetEvent ResetEvent;
67 PFN_vkCreateQueryPool CreateQueryPool;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]68 PFN_vkDestroyQueryPool DestroyQueryPool;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]69 PFN_vkGetQueryPoolResults GetQueryPoolResults;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]70 PFN_vkCreateBuffer CreateBuffer;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]71 PFN_vkDestroyBuffer DestroyBuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]72 PFN_vkCreateBufferView CreateBufferView;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]73 PFN_vkDestroyBufferView DestroyBufferView;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]74 PFN_vkCreateImage CreateImage;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]75 PFN_vkDestroyImage DestroyImage;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]76 PFN_vkGetImageSubresourceLayout GetImageSubresourceLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]77 PFN_vkCreateImageView CreateImageView;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]78 PFN_vkDestroyImageView DestroyImageView;
Chia-I Wuc278df82015-07-07 11:50:03 +0800[diff] [blame]79 PFN_vkCreateAttachmentView CreateAttachmentView;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]80 PFN_vkDestroyAttachmentView DestroyAttachmentView;
Courtney Goeltzenleuchter0b29b0d2015-06-24 18:24:19 -0600[diff] [blame]81 PFN_vkCreateShaderModule CreateShaderModule;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]82 PFN_vkDestroyShaderModule DestroyShaderModule;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]83 PFN_vkCreateShader CreateShader;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]84 PFN_vkDestroyShader DestroyShader;
Jon Ashburn0d60d272015-07-09 15:02:25 -0600[diff] [blame]85 PFN_vkCreatePipelineCache CreatePipelineCache;
86 PFN_vkDestroyPipelineCache DestroyPipelineCache;
87 PFN_vkGetPipelineCacheSize GetPipelineCacheSize;
88 PFN_vkGetPipelineCacheData GetPipelineCacheData;
89 PFN_vkMergePipelineCaches MergePipelineCaches;
90 PFN_vkCreateGraphicsPipelines CreateGraphicsPipelines;
91 PFN_vkCreateComputePipelines CreateComputePipelines;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]92 PFN_vkDestroyPipeline DestroyPipeline;
Mark Lobodzinski556f7212015-04-17 14:11:39 -0500[diff] [blame]93 PFN_vkCreatePipelineLayout CreatePipelineLayout;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]94 PFN_vkDestroyPipelineLayout DestroyPipelineLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]95 PFN_vkCreateSampler CreateSampler;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]96 PFN_vkDestroySampler DestroySampler;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]97 PFN_vkCreateDescriptorSetLayout CreateDescriptorSetLayout;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]98 PFN_vkDestroyDescriptorSetLayout DestroyDescriptorSetLayout;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]99 PFN_vkCreateDescriptorPool CreateDescriptorPool;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]100 PFN_vkDestroyDescriptorPool DestroyDescriptorPool;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]101 PFN_vkResetDescriptorPool ResetDescriptorPool;
102 PFN_vkAllocDescriptorSets AllocDescriptorSets;
Tony Barbourb857d312015-07-10 10:50:45 -0600[diff] [blame]103 PFN_vkFreeDescriptorSets FreeDescriptorSets;
Chia-I Wu8cd8ecd2015-05-25 16:27:55 +0800[diff] [blame]104 PFN_vkUpdateDescriptorSets UpdateDescriptorSets;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]105 PFN_vkCreateDynamicViewportState CreateDynamicViewportState;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]106 PFN_vkDestroyDynamicViewportState DestroyDynamicViewportState;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]107 PFN_vkCreateDynamicRasterState CreateDynamicRasterState;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]108 PFN_vkDestroyDynamicRasterState DestroyDynamicRasterState;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]109 PFN_vkCreateDynamicColorBlendState CreateDynamicColorBlendState;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]110 PFN_vkDestroyDynamicColorBlendState DestroyDynamicColorBlendState;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]111 PFN_vkCreateDynamicDepthStencilState CreateDynamicDepthStencilState;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]112 PFN_vkDestroyDynamicDepthStencilState DestroyDynamicDepthStencilState;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]113 PFN_vkCreateCommandBuffer CreateCommandBuffer;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]114 PFN_vkDestroyCommandBuffer DestroyCommandBuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]115 PFN_vkBeginCommandBuffer BeginCommandBuffer;
116 PFN_vkEndCommandBuffer EndCommandBuffer;
117 PFN_vkResetCommandBuffer ResetCommandBuffer;
118 PFN_vkCmdBindPipeline CmdBindPipeline;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]119 PFN_vkCmdBindDynamicViewportState CmdBindDynamicViewportState;
120 PFN_vkCmdBindDynamicRasterState CmdBindDynamicRasterState;
121 PFN_vkCmdBindDynamicColorBlendState CmdBindDynamicColorBlendState;
122 PFN_vkCmdBindDynamicDepthStencilState CmdBindDynamicDepthStencilState;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]123 PFN_vkCmdBindDescriptorSets CmdBindDescriptorSets;
Courtney Goeltzenleuchter46962942015-04-16 13:38:46 -0600[diff] [blame]124 PFN_vkCmdBindVertexBuffers CmdBindVertexBuffers;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]125 PFN_vkCmdBindIndexBuffer CmdBindIndexBuffer;
126 PFN_vkCmdDraw CmdDraw;
127 PFN_vkCmdDrawIndexed CmdDrawIndexed;
128 PFN_vkCmdDrawIndirect CmdDrawIndirect;
129 PFN_vkCmdDrawIndexedIndirect CmdDrawIndexedIndirect;
130 PFN_vkCmdDispatch CmdDispatch;
131 PFN_vkCmdDispatchIndirect CmdDispatchIndirect;
132 PFN_vkCmdCopyBuffer CmdCopyBuffer;
133 PFN_vkCmdCopyImage CmdCopyImage;
134 PFN_vkCmdBlitImage CmdBlitImage;
135 PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
136 PFN_vkCmdCopyImageToBuffer CmdCopyImageToBuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]137 PFN_vkCmdUpdateBuffer CmdUpdateBuffer;
138 PFN_vkCmdFillBuffer CmdFillBuffer;
139 PFN_vkCmdClearColorImage CmdClearColorImage;
Chris Forbes2951d7d2015-06-22 17:21:59 +1200[diff] [blame]140 PFN_vkCmdClearDepthStencilImage CmdClearDepthStencilImage;
141 PFN_vkCmdClearColorAttachment CmdClearColorAttachment;
142 PFN_vkCmdClearDepthStencilAttachment CmdClearDepthStencilAttachment;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]143 PFN_vkCmdResolveImage CmdResolveImage;
144 PFN_vkCmdSetEvent CmdSetEvent;
145 PFN_vkCmdResetEvent CmdResetEvent;
146 PFN_vkCmdWaitEvents CmdWaitEvents;
147 PFN_vkCmdPipelineBarrier CmdPipelineBarrier;
148 PFN_vkCmdBeginQuery CmdBeginQuery;
149 PFN_vkCmdEndQuery CmdEndQuery;
150 PFN_vkCmdResetQueryPool CmdResetQueryPool;
151 PFN_vkCmdWriteTimestamp CmdWriteTimestamp;
Courtney Goeltzenleuchter98049062015-04-15 18:21:13 -0600[diff] [blame]152 PFN_vkCmdCopyQueryPoolResults CmdCopyQueryPoolResults;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]153 PFN_vkCreateFramebuffer CreateFramebuffer;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]154 PFN_vkDestroyFramebuffer DestroyFramebuffer;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]155 PFN_vkCreateRenderPass CreateRenderPass;
Tony Barbourde4124d2015-07-03 10:33:54 -0600[diff] [blame]156 PFN_vkDestroyRenderPass DestroyRenderPass;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]157 PFN_vkCmdBeginRenderPass CmdBeginRenderPass;
Chia-I Wuc278df82015-07-07 11:50:03 +0800[diff] [blame]158 PFN_vkCmdNextSubpass CmdNextSubpass;
Courtney Goeltzenleuchter382489d2015-04-10 08:34:15 -0600[diff] [blame]159 PFN_vkCmdEndRenderPass CmdEndRenderPass;
Chia-I Wu88eaa3b2015-06-26 15:34:39 +0800[diff] [blame]160 PFN_vkCmdExecuteCommands CmdExecuteCommands;
Chia-I Wu5b66aa52015-04-16 22:02:10 +0800[diff] [blame]161 PFN_vkCreateSwapChainWSI CreateSwapChainWSI;
162 PFN_vkDestroySwapChainWSI DestroySwapChainWSI;
163 PFN_vkGetSwapChainInfoWSI GetSwapChainInfoWSI;
164 PFN_vkQueuePresentWSI QueuePresentWSI;
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]165 PFN_vkDbgCreateMsgCallback DbgCreateMsgCallback;
166 PFN_vkDbgDestroyMsgCallback DbgDestroyMsgCallback;
167 PFN_vkDbgStringCallback DbgStringCallback;
168 PFN_vkDbgStdioCallback DbgStdioCallback;
169 PFN_vkDbgBreakCallback DbgBreakCallback;
Jon Ashburn301c5f02015-04-06 10:58:22 -0600[diff] [blame]170} VkLayerDispatchTable;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]171
Jon Ashburn9a9bb642015-05-04 16:27:53 -0600[diff] [blame]172typedef struct VkLayerInstanceDispatchTable_
173{
174 PFN_vkGetInstanceProcAddr GetInstanceProcAddr;
Jon Ashburn52c1d732015-05-12 17:23:55 -0600[diff] [blame]175 PFN_vkCreateInstance CreateInstance;
Jon Ashburn9a9bb642015-05-04 16:27:53 -0600[diff] [blame]176 PFN_vkDestroyInstance DestroyInstance;
177 PFN_vkEnumeratePhysicalDevices EnumeratePhysicalDevices;
Chris Forbesd7576302015-06-21 22:55:02 +1200[diff] [blame]178 PFN_vkGetPhysicalDeviceFeatures GetPhysicalDeviceFeatures;
179 PFN_vkGetPhysicalDeviceFormatInfo GetPhysicalDeviceFormatInfo;
180 PFN_vkGetPhysicalDeviceLimits GetPhysicalDeviceLimits;
Mark Lobodzinski83d4e6a2015-07-03 15:58:09 -0600[diff] [blame]181 PFN_vkGetPhysicalDeviceSparseImageFormatProperties GetPhysicalDeviceSparseImageFormatProperties;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]182 PFN_vkGetPhysicalDeviceProperties GetPhysicalDeviceProperties;
183 PFN_vkGetPhysicalDevicePerformance GetPhysicalDevicePerformance;
184 PFN_vkGetPhysicalDeviceQueueCount GetPhysicalDeviceQueueCount;
185 PFN_vkGetPhysicalDeviceQueueProperties GetPhysicalDeviceQueueProperties;
186 PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties;
Tony Barbour426b9052015-06-24 16:06:58 -0600[diff] [blame]187 PFN_vkGetPhysicalDeviceExtensionProperties GetPhysicalDeviceExtensionProperties;
Courtney Goeltzenleuchter18061cd2015-06-29 15:39:26 -0600[diff] [blame]188 PFN_vkGetPhysicalDeviceLayerProperties GetPhysicalDeviceLayerProperties;
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]189 PFN_vkDbgCreateMsgCallback DbgCreateMsgCallback;
190 PFN_vkDbgDestroyMsgCallback DbgDestroyMsgCallback;
191 PFN_vkDbgStringCallback DbgStringCallback;
192 PFN_vkDbgStdioCallback DbgStdioCallback;
193 PFN_vkDbgBreakCallback DbgBreakCallback;
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,
211 VK_DBG_LAYER_ACTION_BREAK = 0x4
Courtney Goeltzenleuchter1c7c65d2015-06-10 17:39:03 -0600[diff] [blame]212} VkLayerDbgAction;
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]213
Courtney Goeltzenleuchter89e99e62015-04-08 18:04:29 -0600[diff] [blame]214// ------------------------------------------------------------------------------------------------
215// API functions