General interface
-----------------

The ATC compression and decompression functions can be split into three categories, each with their own task:

* ``compress``: Compression
* ``decompress``: Decompression
* ``compress_decompress``: Compression followed by immediate decompression of the dataset. These functions can provide extra functionality over a ``compress`` call followed by a `decompress` call because they allow the user to request error calculation using the option ``calculate_error``, i.e. the exact decompression error will be calculated and returned. To achieve this, the original data is only loaded once and is kept in memory for comparison later. Although this decreases IO in case the original data was stored in a file, this also increases peak memory usage, so depending on the user's needs ``compress_decompress`` may or may not be the right function to call.

Furthermore, the original, compressed and decompressed data can be passed in/out in three different ways:

* As a file, by providing a path (``std::string``)
* As a buffer in-memory, by passing the buffer size (``size_t``) and a pointer to the first element (``dtype*`` in the case of original/decompressed data, ``char*`` in the case of compressed data). ATC will never read or write past the given buffer size.
* As a buffer in-memory, by passing a vector (``std::vector<dtype>`` in the case of original/decompressed data, ``std::vector<char>`` in the case of compressed data). When returning data using vectors, this is done using the :any:`atc::Results` and :any:`atc::TypedResults` structs.

Because of all these combinations, there are a lot of "instantiations" of ``compress``, ``decompress`` and ``compress_decompress``, although they only differ in terms of the data interface they provide. Therefore, we will only provide some documentation for each group as a whole. Note that each of these calls takes an optional :any:`atc::Options` argument, which is covered on the :ref:`Options page <options>`. Also, there are no functions which output compressed data into a user-provided pointer (the second case in the aforementioned list), because the user cannot determine the appropriate buffer size beforehand.

As for the return values of these functions, we refer to the :ref:`Results page <results>`. Moreover, most ATC calls can throw exceptions, mostly because of invalid arguments. Since their error messages should already be descriptive enough on their own, these are not documented here.

Finally, ATC also provides some utility functions, which are documented at the end of this page.

.. _cpp_atc_compress:

atc::compress
~~~~~~~~~~~~~

Apart from the original/compressed data and options arguments, which were covered at the start of this page, ``compress`` functions take the following arguments:

- :any:`atc::DataType` `data_type`: Only necessary when passing the original data as a file. Because the original data is not passed as a typed buffer, ATC needs to be explicitly told about the data type of the original data.
- ``std::vector<size_t>`` `sizes`: The mode sizes of the original data tensor.
- ``double`` `target_error`: The target error, represented in the error metric stored in the option ``error_metric`` (default: PSNR, i.e. peak signal-to-noise ratio).

Note that when there is no ``compressed_file`` argument specified, this indicates the compressed output is being returned using as an ``std::vector<char>`` using the field ``compressed_data`` inside :any:`atc::Results`.

.. doxygengroup:: compress
   :content-only:
   :members:

.. _cpp_atc_decompress:

atc::decompress
~~~~~~~~~~~~~~~

Apart from the compressed/decompressed data and options arguments, which were covered at the start of this page, ``decompress`` functions do not take any arguments, since all metadata is already stored in the compressed data. Note that when there is no ``decompressed_file`` or ``decompressed_data`` argument specified, this indicates the decompressed output is being returned using as an ``std::vector<dtype>`` using the field ``decompressed_data`` inside :any:`atc::TypedResults`.

.. doxygengroup:: decompress
   :content-only:
   :members:

.. _cpp_atc_compress_decompress:

atc::compress_decompress
~~~~~~~~~~~~~~~~~~~~~~~~

In terms of the interface, the ``compress_decompress`` functions are simply a combination of the aforementioned ``compress`` and ``decompress`` functions described. Therefore, we do not provide specific documentation for this group.

.. doxygengroup:: compdecomp
   :content-only:
   :members:

.. _cpp_atc_read_data_type:

atc::read_data_type
~~~~~~~~~~~~~~~~~~~

The following functions determine the original data type of a compressed output object. This can be useful when decompressing into memory so a buffer of the appropriate type can be pre-allocated.

.. doxygengroup:: rdtype
   :content-only:
   :members:

.. _cpp_atc_read_decompressed_size:

atc::read_decompressed_size
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following functions determine the size (i.e. the number of elements) of the decompressed output if the given compressed output object were to be decompressed with the given decompression options, specifically depending on the given cut-out. This can be useful when decompressing into memory so a buffer of the appropriate size can be pre-allocated. Note that when autocrop is enabled, we cannot exactly predict the final decompressed size so we assume nothing is cropped and return a safe upper bound.

.. doxygengroup:: rdsize
   :content-only:
   :members:

.. _cpp_atc_calculate_decompressed_size:

atc::calculate_decompressed_size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. doxygengroup:: cdsize
   :content-only:
   :members:

atc::DataType
~~~~~~~~~~~~~

.. doxygenenum:: DataType

.. doxygenfunction:: get_data_type

atc::version
~~~~~~~~~~~~

.. doxygenvariable:: version
