Writing Compressed TIFF Files
==============================

This example demonstrates how to write compressed images to TIFF files using the
Jetraw TIFF library.

The Jetraw TIFF library provides a convenient API for working with TIFF files. This
example shows the complete workflow: opening a file, appending compressed images, and
closing the file.

Example
-------

.. code-block:: cpp

   #include "dpcore/dpcore.h"
   #include "jetraw_tiff/jetraw_tiff.h"
   #include "jetraw/dp_status.h"
   #include <iostream>

   int main() {
       // Initialize Jetraw TIFF library
       jetraw_tiff_init();
       jetraw_tiff_set_license("");

       // Load calibration parameters
       dpcore_load_parameters("./calibration.dat");

       // Assume image buffer is already loaded and prepared
       uint16_t* imageBuffer;
       uint32_t WIDTH = 2560;
       uint32_t HEIGHT = 2160;

       // Open a TIFF file for writing
       dp_tiff* handle = nullptr;
       dp_status status = jetraw_tiff_open(
           "./output_compressed.tiff",
           WIDTH,
           HEIGHT,
           "Compressed TIFF file description",
           &handle,
           "w"  // "w" for write mode
       );

       if (status != dp_success) {
           std::cerr << "Failed to open TIFF file: "
                     << dp_status_description(status) << '\n';
           return 1;
       }

       // Append the compressed image to the TIFF file
       status = jetraw_tiff_append(handle, imageBuffer);
       if (status != dp_success) {
           std::cerr << "Failed to append image: "
                     << dp_status_description(status) << '\n';
           jetraw_tiff_close(&handle);
           return 1;
       }

       // Close the TIFF file (writes all data to disk)
       status = jetraw_tiff_close(&handle);
       if (status != dp_success) {
           std::cerr << "Failed to close TIFF file: "
                     << dp_status_description(status) << '\n';
           return 1;
       }

       return 0;
   }

Important Notes
---------------

.. warning::
   If a file already exists at the given path, it will be overwritten and replaced
   with an empty file containing only the description.

- The image buffer must be prepared (using ``dpcore_prepare_image()`` or
  ``dpcore_embed_meta()``) before calling ``jetraw_tiff_append()``.
- All images appended to the same file must have the same dimensions (WIDTH × HEIGHT).
- The file handle is set to ``nullptr`` after ``jetraw_tiff_close()`` succeeds.

See Also
--------

- :c:func:`jetraw_tiff_open`
- :c:func:`jetraw_tiff_append`
- :c:func:`jetraw_tiff_close`
- :doc:`multi_page_tiff` for handling multiple pages
- :doc:`../c_libraries` for complete API reference