Merge remote-tracking branch 'upstream/main' into standalone-sequence-4

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,

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 */