API Reference

Core Types

enum VcDtype

Column data type enumeration. Represents the element type of a GPU column buffer.

enumerator VC_DTYPE_U8 = 0

enumerator VC_DTYPE_U16 = 1

enumerator VC_DTYPE_U32 = 2

enumerator VC_DTYPE_U64 = 3

enumerator VC_DTYPE_I8 = 4

enumerator VC_DTYPE_I16 = 5

enumerator VC_DTYPE_I32 = 6

enumerator VC_DTYPE_I64 = 7

enumerator VC_DTYPE_F32 = 8

enumerator VC_DTYPE_F64 = 9

type VcContext: Opaque handle to a GPU context. Created by vc_create_context() and destroyed by vc_destroy_context(). Manages Vulkan instance, physical device, logical device, queue, command pool, and VMA allocator.

type VcColumn: Opaque handle to a typed column buffer on the GPU. Created by vc_create_column() and destroyed by vc_destroy_column(). Internal layout is not part of the public ABI.

Context Lifecycle

VcContext *vc_create_context(void)

Create a GPU context. Selects the first available AMD GPU with a compute queue (falls back to any compute-capable GPU if no AMD GPU is found). Enables Vulkan validation layers in debug builds.

Returns:: A new context, or NULL on failure.
Return type:: VcContext*

void vc_destroy_context(VcContext *ctx): Destroy a GPU context and all associated resources. Passing NULL is a no-op.

Column Management

VcColumn *vc_create_column(VcContext *ctx, VcDtype dtype, uint64_t length, const void *host_data)

Allocate a typed column on the GPU and optionally upload host data.

Parameters:

ctx – GPU context.
dtype – Element data type.
length – Number of elements.
host_data – Pointer to host data to upload, or NULL to leave uninitialized.

Returns:

A new column, or NULL on failure.

Return type:

VcColumn*

void vc_destroy_column(VcContext *ctx, VcColumn *col): Free a GPU column and its backing buffer. Passing NULL for either argument is a no-op.

int vc_read_column(VcContext *ctx, VcColumn *col, void *host_buffer, uint64_t host_buffer_size)

Read column data back from GPU to host memory. Uses a staging buffer and pipeline barriers to ensure correct synchronization.

Parameters:

ctx – GPU context.
col – Column to read.
host_buffer – Destination buffer on the host.
host_buffer_size – Size of the destination buffer in bytes.

Returns:

0 on success, non-zero on error (e.g., buffer too small).

uint64_t vc_column_length(VcColumn *col): Return the number of elements in the column. Returns 0 if col is NULL.

VcDtype vc_column_dtype(VcColumn *col): Return the data type of the column elements. Returns VC_DTYPE_U8 if col is NULL.

Operations

VcColumn *vc_filter(VcContext *ctx, VcColumn *data_col, VcColumn *mask_col, uint64_t *out_length)

Filter a column by a boolean mask (stream compaction). Returns a new column containing only elements where the mask is non-zero.

Status: Stub — returns NULL. Stream compaction implementation planned for Phase 2.

VcColumn *vc_cast(VcContext *ctx, VcColumn *col, VcDtype target_dtype)

Cast a column to a different numeric data type (element-wise conversion).

Status: Stub — returns NULL. Type casting implementation planned for Phase 3.

Utilities

uint32_t vc_dtype_size(VcDtype dtype): Return the size in bytes of the given data type.