Getting Started
===============

Prerequisites
-------------

- Vulkan SDK 1.3+ (provides ``glslc`` compiler and ``vulkan.h``)
- CMake 3.20+
- GCC 13+ or Clang 17+ (C++20)
- ``xxd`` (part of vim-common on Linux, Git Bash on Windows)

Building
--------

.. code-block:: bash

    cmake -B build -DCMAKE_BUILD_TYPE=Release
    cmake --build build

This builds the ``vc_core`` static library, plus ``vc_filter`` and ``vc_cast``
stubs.  Production builds omit tests and benchmarks.

.. note::

   ``vc_create_context``, ``vc_create_column``, ``vc_read_column``,
   ``vc_filter``, and ``vc_cast`` are currently stubs that return ``NULL``.
   Only ``vc_dtype_size`` is functional.

Running Tests
-------------

.. code-block:: bash

    cmake -B build -DCMAKE_BUILD_TYPE=Debug -DVC_BUILD_TESTS=ON
    cmake --build build
    cd build && ctest --output-on-failure

Debug builds enable Vulkan validation layers automatically.  Tests should
pass with zero validation errors.

Hello Compute
-------------

Verify your Vulkan toolchain with the standalone sandbox spike:

.. code-block:: bash

    cmake -B build -DVC_SANDBOX=ON \
      -DVulkan_INCLUDE_DIR=$VULKAN_SDK/Include \
      -DVulkan_LIBRARY=$VULKAN_SDK/Lib/vulkan-1.lib
    cmake --build build --target hello_compute
    ./build/sandbox/hello_compute

Expected output:

.. code-block::

    GPU: AMD Radeon RX 9070 (Vulkan 1.4.329)
    PASS: All 1024 elements correctly incremented.

Library Usage (C API)
---------------------

.. code-block:: c

    #include "vulkan_columnar/vc_context.h"
    #include <stdio.h>

    int main() {
        printf("U32 element size: %u bytes\n", vc_dtype_size(VC_DTYPE_U32));
        printf("F64 element size: %u bytes\n", vc_dtype_size(VC_DTYPE_F64));
        return 0;
    }