diff --git a/include/acquire.zarr.h b/include/acquire.zarr.h index cbbbaf86..54a7288a 100644 --- a/include/acquire.zarr.h +++ b/include/acquire.zarr.h @@ -7,17 +7,32 @@ extern "C" { #endif + /** + * @brief The settings for a Zarr stream. + * @details This struct contains the settings for a Zarr stream, including + * the store path, custom metadata, S3 settings, chunk compression settings, + * dimension properties, whether to stream to multiple levels of detail, the + * pixel data type, and the Zarr format version. + * @note The store path can be a filesystem path or an S3 key prefix. For example, + * supplying an endpoint "s3://my-endpoint.com" and a bucket "my-bucket" with a + * store_path of "my-dataset.zarr" will result in the store being written to + * "s3://my-endpoint.com/my-bucket/my-dataset.zarr". + * @note The dimensions array may be allocated with ZarrStreamSettings_create_dimension_array + * and freed with ZarrStreamSettings_destroy_dimension_array. The order in which you + * set the dimension properties in the array should match the order of the dimensions + * from slowest to fastest changing, for example, [Z, Y, X] for a 3D dataset. + */ typedef struct ZarrStreamSettings_s { - ZarrS3Settings s3_settings; - ZarrCompressionSettings compression_settings; - ZarrDimensionProperties* dimensions; - size_t dimension_count; - char* store_path; - char* custom_metadata; - ZarrDataType data_type; - ZarrVersion version; - bool multiscale; + const char* store_path; /**< Path to the store. Filesystem path or S3 key prefix. */ + const char* custom_metadata; /**< JSON-formatted custom metadata to be stored with the dataset. */ + ZarrS3Settings* s3_settings; /**< Optional S3 settings for the store. */ + ZarrCompressionSettings* compression_settings; /**< Optional chunk compression settings for the store. */ + ZarrDimensionProperties* dimensions; /**< The properties of each dimension in the dataset. */ + size_t dimension_count; /**< The number of dimensions in the dataset. */ + bool multiscale; /**< Whether to stream to multiple levels of detail. */ + ZarrDataType data_type; /**< The pixel data type of the dataset. */ + ZarrVersion version; /**< The version of the Zarr format to use. 2 or 3. */ } ZarrStreamSettings; typedef struct ZarrStream_s ZarrStream; @@ -31,7 +46,7 @@ extern "C" /** * @brief Set the log level for the Zarr API. * @param level The log level. - * @return ZarrStatus_Success on success, or an error code on failure. + * @return ZarrStatusCode_Success on success, or an error code on failure. */ ZarrStatusCode Zarr_set_log_level(ZarrLogLevel level); @@ -48,14 +63,26 @@ extern "C" */ const char* Zarr_get_status_message(ZarrStatusCode status); + /** + * @brief Allocate memory for the dimension array in the Zarr stream settings struct. + * @param[in, out] settings The Zarr stream settings struct. + * @param dimension_count The number of dimensions in the dataset to allocate memory for. + * @return ZarrStatusCode_Success on success, or an error code on failure. + */ + ZarrStatusCode ZarrStreamSettings_create_dimension_array(ZarrStreamSettings* settings, size_t dimension_count); + + /** + * @brief Free memory for the dimension array in the Zarr stream settings struct. + * @param[in, out] settings The Zarr stream settings struct containing the dimension array to free. + */ + void ZarrStreamSettings_destroy_dimension_array(ZarrStreamSettings* settings); + /** * @brief Create a Zarr stream. * @param[in, out] settings The settings for the Zarr stream. - * @param[in] version The version of the Zarr stream. 2 or 3. * @return A pointer to the Zarr stream struct, or NULL on failure. */ - ZarrStream* ZarrStream_create(ZarrStreamSettings* settings, - ZarrVersion version); + ZarrStream* ZarrStream_create(ZarrStreamSettings* settings); /** * @brief Destroy a Zarr stream. @@ -73,7 +100,7 @@ extern "C" * @param[in] bytes_in The number of bytes in @p data. It should be at least * the size of a single frame. * @param[out] bytes_out The number of bytes written to the stream. - * @return ZarrStatus_Success on success, or an error code on failure. + * @return ZarrStatusCode_Success on success, or an error code on failure. */ ZarrStatusCode ZarrStream_append(ZarrStream* stream, const void* data, diff --git a/include/zarr.types.h b/include/zarr.types.h index 2dfd0dd1..6e04c03d 100644 --- a/include/zarr.types.h +++ b/include/zarr.types.h @@ -12,17 +12,17 @@ extern "C" typedef enum { - ZarrStatus_Success = 0, - ZarrStatus_InvalidArgument, - ZarrStatus_Overflow, - ZarrStatus_InvalidIndex, - ZarrStatus_NotYetImplemented, - ZarrStatus_InternalError, - ZarrStatus_OutOfMemory, - ZarrStatus_IOError, - ZarrStatus_CompressionError, - ZarrStatus_InvalidSettings, - ZarrStatusCount, + ZarrStatusCode_Success = 0, + ZarrStatusCode_InvalidArgument, + ZarrStatusCode_Overflow, + ZarrStatusCode_InvalidIndex, + ZarrStatusCode_NotYetImplemented, + ZarrStatusCode_InternalError, + ZarrStatusCode_OutOfMemory, + ZarrStatusCode_IOError, + ZarrStatusCode_CompressionError, + ZarrStatusCode_InvalidSettings, + ZarrStatusCodeCount, } ZarrStatusCode; typedef enum @@ -112,7 +112,6 @@ extern "C" typedef struct { const char* name; /**< Name of the dimension */ - size_t bytes_of_name; /**< Bytes in @p name, including null terminator */ ZarrDimensionType type; /**< Type of the dimension */ uint32_t array_size_px; /**< Size of the array along this dimension in pixels */