extract new header heif_uncompressed.h from heif_experimental.h

Author: farindk

examples/heif_enc.cc

@@ -55,6 +55,7 @@
 #include "libheif/api_structs.h"
 #include "libheif/heif_experimental.h"
 #include "libheif/heif_sequences.h"
+#include "libheif/heif_uncompressed.h"
 
 // --- command line parameters
 

libheif/CMakeLists.txt

@@ -24,6 +24,7 @@ set(libheif_headers
         api/libheif/heif_image_handle.h
         api/libheif/heif_context.h
         api/libheif/heif_tiling.h
+        api/libheif/heif_uncompressed.h
         api/libheif/heif_cxx.h
         ${CMAKE_CURRENT_BINARY_DIR}/heif_version.h)
 
@@ -80,6 +81,7 @@ set(libheif_sources
         api/libheif/heif_image_handle.cc
         api/libheif/heif_context.cc
         api/libheif/heif_tiling.cc
+        api/libheif/heif_uncompressed.cc
         codecs/decoder.h
         codecs/decoder.cc
         codecs/encoder.h

libheif/api/libheif/heif_experimental.cc

@@ -369,35 +369,6 @@ void heif_pyramid_layer_info_release(struct heif_pyramid_layer_info* infos)
 }
 
 
-struct heif_error heif_context_add_unci_image(struct heif_context* ctx,
-                                              const struct heif_unci_image_parameters* parameters,
-                                              const struct heif_encoding_options* encoding_options,
-                                              const heif_image* prototype,
-                                              struct heif_image_handle** out_unci_image_handle)
-{
-#if WITH_UNCOMPRESSED_CODEC
-  Result<std::shared_ptr<ImageItem_uncompressed>> unciImageResult;
-  unciImageResult = ImageItem_uncompressed::add_unci_item(ctx->context.get(), parameters, encoding_options, prototype->image);
-
-  if (unciImageResult.error != Error::Ok) {
-    return unciImageResult.error.error_struct(ctx->context.get());
-  }
-
-  if (out_unci_image_handle) {
-    *out_unci_image_handle = new heif_image_handle;
-    (*out_unci_image_handle)->image = unciImageResult.value;
-    (*out_unci_image_handle)->context = ctx->context;
-  }
-
-  return heif_error_success;
-#else
-  return {heif_error_Unsupported_feature,
-          heif_suberror_Unspecified,
-          "support for uncompressed images (ISO23001-17) has been disabled."};
-#endif
-}
-
-
 struct heif_error heif_image_add_channel(struct heif_image* image,
                                          enum heif_channel channel,
                                          int width, int height,

libheif/api/libheif/heif_experimental.h

@@ -149,46 +149,6 @@ struct heif_error heif_context_add_tiled_image(struct heif_context* ctx,
                                                struct heif_image_handle** out_tiled_image_handle);
 #endif
 
-// --- 'unci' images
-
-// This is similar to heif_metadata_compression. We should try to keep the integers compatible, but each enum will just
-// contain the allowed values.
-enum heif_unci_compression
-{
-  heif_unci_compression_off = 0,
-  //heif_unci_compression_auto = 1,
-  //heif_unci_compression_unknown = 2, // only used when reading unknown method from input file
-  heif_unci_compression_deflate = 3,
-  heif_unci_compression_zlib = 4,
-  heif_unci_compression_brotli = 5
-};
-
-
-struct heif_unci_image_parameters {
-  int version;
-
-  // --- version 1
-
-  uint32_t image_width;
-  uint32_t image_height;
-
-  uint32_t tile_width;
-  uint32_t tile_height;
-
-  enum heif_unci_compression compression; // TODO
-
-  // TODO: interleave type, padding
-};
-
-#if HEIF_ENABLE_EXPERIMENTAL_FEATURES
-LIBHEIF_API
-struct heif_error heif_context_add_unci_image(struct heif_context* ctx,
-                                              const struct heif_unci_image_parameters* parameters,
-                                              const struct heif_encoding_options* encoding_options,
-                                              const struct heif_image* prototype,
-                                              struct heif_image_handle** out_unci_image_handle);
-#endif
-
 // --- 'pymd' entity group (pyramid layers)
 
 struct heif_pyramid_layer_info {

libheif/api/libheif/heif_uncompressed.cc

@@ -0,0 +1,67 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2024 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * This file is part of libheif.
+ *
+ * libheif is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * libheif is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "heif_uncompressed.h"
+#include "context.h"
+#include "api_structs.h"
+#include "image-items/unc_image.h"
+
+#include <array>
+#include <memory>
+
+
+struct heif_error heif_context_add_unci_image(struct heif_context* ctx,
+                                              const struct heif_unci_image_parameters* parameters,
+                                              const struct heif_encoding_options* encoding_options,
+                                              const heif_image* prototype,
+                                              struct heif_image_handle** out_unci_image_handle)
+{
+#if WITH_UNCOMPRESSED_CODEC
+  if (prototype == nullptr) {
+    return {heif_error_Usage_error,
+            heif_suberror_Null_pointer_argument,
+            "prototype image is NULL"};
+  }
+
+  if (out_unci_image_handle == nullptr) {
+    return {heif_error_Usage_error,
+            heif_suberror_Null_pointer_argument,
+            "out_unci_image_handle image is NULL"};
+  }
+
+  Result<std::shared_ptr<ImageItem_uncompressed>> unciImageResult;
+  unciImageResult = ImageItem_uncompressed::add_unci_item(ctx->context.get(), parameters, encoding_options, prototype->image);
+
+  if (unciImageResult.error != Error::Ok) {
+    return unciImageResult.error.error_struct(ctx->context.get());
+  }
+
+  assert(out_unci_image_handle);
+  *out_unci_image_handle = new heif_image_handle;
+  (*out_unci_image_handle)->image = unciImageResult.value;
+  (*out_unci_image_handle)->context = ctx->context;
+
+  return heif_error_success;
+#else
+  return {heif_error_Unsupported_feature,
+          heif_suberror_Unspecified,
+          "support for uncompressed images (ISO23001-17) has been disabled."};
+#endif
+}

libheif/api/libheif/heif_uncompressed.h

@@ -0,0 +1,108 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2024-2025 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * This file is part of libheif.
+ *
+ * libheif is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * libheif is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef LIBHEIF_HEIF_UNCOMPRESSED_H
+#define LIBHEIF_HEIF_UNCOMPRESSED_H
+
+#include "libheif/heif.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* @file heif_uncompressed.h
+ * @brief Functions for adding ISO 23001-17 (uncompressed) images to a HEIF file.
+ *        Despite its name, this is not limited to uncompressed images.
+ *        It is also possible to add images with lossless compression methods.
+ *        See heif_metadata_compression for more information.
+ */
+
+// --- 'unci' images
+
+// This is similar to heif_metadata_compression. We should try to keep the integers compatible, but each enum will just
+// contain the allowed values.
+enum heif_unci_compression
+{
+  heif_unci_compression_off = 0,
+  //heif_unci_compression_auto = 1,
+  //heif_unci_compression_unknown = 2, // only used when reading unknown method from input file
+  heif_unci_compression_deflate = 3,
+  heif_unci_compression_zlib = 4,
+  heif_unci_compression_brotli = 5
+};
+
+
+struct heif_unci_image_parameters {
+  int version;
+
+  // --- version 1
+
+  uint32_t image_width;
+  uint32_t image_height;
+
+  uint32_t tile_width;
+  uint32_t tile_height;
+
+  enum heif_unci_compression compression;
+
+  // TODO: interleave type, padding
+};
+
+LIBHEIF_API
+struct heif_unci_image_parameters* heif_unci_image_parameters_alloc();
+
+LIBHEIF_API
+void heif_unci_image_parameters_copy(struct heif_unci_image_parameters* dst,
+                                     const struct heif_unci_image_parameters* src);
+
+LIBHEIF_API
+void heif_unci_image_parameters_release(struct heif_unci_image_parameters*);
+
+
+/*
+ * This adds an empty iso23001-17 (uncompressed) image to the HEIF file.
+ * The actual image data is addded later using heif_context_add_image_tile().
+ * If you do not need tiling, you can use heif_context_encode_image() instead.
+ * However, this will by default disable any compression and any control about
+ * the data layout.
+ *
+ * @param ctx The file context
+ * @param parameters The parameters for the image, must not be NULL.
+ * @param encoding_options Optional, may be NULL.
+ * @param prototype An image with the same channel configuration as the image data
+ *                  that will be later inserted. The image size need not match this.
+ *                  Must not be NULL.
+ * @param out_unci_image_handle Returns a handle to the image. The caller is responsible for freeing it.
+ *                  Must not be NULL because this is required to fill in image data.
+ * @return Returns an error if the passed parameters are incorrect.
+ *         If ISO23001-17 images are not supported, returns heif_error_Unsupported_feature.
+ */
+LIBHEIF_API
+struct heif_error heif_context_add_unci_image(struct heif_context* ctx,
+                                              const struct heif_unci_image_parameters* parameters,
+                                              const struct heif_encoding_options* encoding_options,
+                                              const struct heif_image* prototype,
+                                              struct heif_image_handle** out_unci_image_handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

libheif/codecs/uncompressed/unc_codec.h

@@ -25,6 +25,8 @@
 #include "pixelimage.h"
 #include "file.h"
 #include "context.h"
+#include "libheif/heif_uncompressed.h"
+
 #if WITH_UNCOMPRESSED_CODEC
 #include "unc_boxes.h"
 #endif

libheif/image-items/unc_image.h

@@ -25,6 +25,7 @@
 #include "pixelimage.h"
 #include "file.h"
 #include "context.h"
+#include "libheif/heif_uncompressed.h"
 
 #include <cstdint>
 #include <string>