Jetraw Core FPGA implementation 
===============================

Jetraw Core is also implemented in VHDL for deployment to FPGAs. Information
about the FPGA implementation is available on demand by contacting Dotphoton
directly. This section of the documentation focuses on using the software
implementation to decode compressed buffers produced by the FPGA implementation.

Compressed buffer format
~~~~~~~~~~~~~~~~~~~~~~~~~

It is important to save the compressed buffer generated by the FPGA
implementation "as-is", without adding any padding at the beginning or end of
the file. Introducing padding will cause the decoding process to fail.

Compatibility with software tools and libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently, FPGA-generated compressed buffers are only compatible with the direct
image buffer decoding function, ``jetraw_decode``, provided by the C library. It
is not possible to decode any FPGA-generated compressed buffers using the GUI,
the CLI, or the TIFF-related functions.

Decoding FPGA compressed buffers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example code shows how to decode FPGA-encoded image buffers. The
output of the ``jetraw_decode`` function is still a raw image buffer; additional
logic is required to store the buffer into a more convenient container.

.. note::
   You must know the image dimensions (width and height) before decoding, as
   these are required parameters for ``jetraw_decode()``.

.. code-block:: cpp
    
    // Copyright 2025 Dotphoton AG
    #include <iostream>
    #include <fstream>
    #include <filesystem>
    #include <vector>

    #include "jetraw/jetraw.h"
    #include "jetraw/dp_status.h"

    int main(int argc, char** argv) {
        std::filesystem::path source_path("<path-to-encoded-buffer>");
        auto image_height = <decoded-height>;
        auto image_width = <decoded-width>;

        // Load compressed buffer from file
        std::ifstream source_stream(source_path, std::ios::binary);
        if (!source_stream) {
            std::cerr << "Failed to open compressed buffer file\n";
            return 1;
        }

        std::vector<char> source_buffer(std::filesystem::file_size(source_path));
        source_stream.read(source_buffer.data(), source_buffer.size());

        // Prepare destination buffer
        std::vector<uint16_t> destination_buffer(image_height * image_width);

        // Decode image
        auto status = jetraw_decode(
            source_buffer.data(), 
            source_buffer.size(), 
            destination_buffer.data(), 
            image_height * image_width
        );

        // Check status
        if (status != dp_success) {
            std::cerr << "Decoding failed: "
                      << dp_status_description(status) << std::endl;
            return 1;
        }

        // destination_buffer now contains the decompressed image data
        // Additional logic needed to save it to a file format (e.g., TIFF)

        return 0;
    }