Commit 14a689a2 for libheif
commit 14a689a2f0a13a5bd809fc1ebec4cc447209752a
Author: Dirk Farin <dirk.farin@gmail.com>
Date: Wed May 27 13:21:37 2026 +0200
rename component_idx parameters to component_id in heif_components
The heif_image_* component accessors in heif_components.h used the parameter
name `component_idx` (and the "index-based" section comment), but these values
are component IDs from the same ID space as the heif_image_handle_* accessors
(as the header itself documents: the IDs match those reported by
heif_image_get_used_component_ids()). Rename the parameters to `component_id`
and fix the stale "index" wording in the comments. This is a parameter-name /
documentation change only; the ABI is unaffected.
diff --git a/libheif/api/libheif/heif_components.cc b/libheif/api/libheif/heif_components.cc
index 4d82f977..cf5f1b79 100644
--- a/libheif/api/libheif/heif_components.cc
+++ b/libheif/api/libheif/heif_components.cc
@@ -47,57 +47,57 @@ void heif_image_get_used_component_ids(const heif_image* image, uint32_t* out_co
}
-heif_channel heif_image_get_component_channel(const heif_image* image, uint32_t component_idx)
+heif_channel heif_image_get_component_channel(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return heif_channel_Y;
}
- return image->image->get_component_channel(component_idx);
+ return image->image->get_component_channel(component_id);
}
-uint32_t heif_image_get_component_width(const heif_image* image, uint32_t component_idx)
+uint32_t heif_image_get_component_width(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return 0;
}
- return image->image->get_component_width(component_idx);
+ return image->image->get_component_width(component_id);
}
-uint32_t heif_image_get_component_height(const heif_image* image, uint32_t component_idx)
+uint32_t heif_image_get_component_height(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return 0;
}
- return image->image->get_component_height(component_idx);
+ return image->image->get_component_height(component_id);
}
-int heif_image_get_component_bits_per_pixel(const heif_image* image, uint32_t component_idx)
+int heif_image_get_component_bits_per_pixel(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return 0;
}
- return image->image->get_component_bits_per_pixel(component_idx);
+ return image->image->get_component_bits_per_pixel(component_id);
}
-uint16_t heif_image_get_component_type(const heif_image* image, uint32_t component_idx)
+uint16_t heif_image_get_component_type(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return 0;
}
- return image->image->get_component_type(component_idx);
+ return image->image->get_component_type(component_id);
}
-heif_component_datatype heif_image_get_component_datatype(const heif_image* image, uint32_t component_idx)
+heif_component_datatype heif_image_get_component_datatype(const heif_image* image, uint32_t component_id)
{
if (!image || !image->image) {
return heif_component_datatype_undefined;
}
- return image->image->get_component_datatype(component_idx);
+ return image->image->get_component_datatype(component_id);
}
@@ -172,7 +172,7 @@ heif_error heif_image_add_component(heif_image* image,
uint16_t component_type,
heif_component_datatype datatype,
int bit_depth,
- uint32_t* out_component_idx)
+ uint32_t* out_component_id)
{
if (!image || !image->image) {
return heif_error_null_pointer_argument;
@@ -183,8 +183,8 @@ heif_error heif_image_add_component(heif_image* image,
return result.error_struct(image->image.get());
}
- if (out_component_idx) {
- *out_component_idx = *result;
+ if (out_component_id) {
+ *out_component_id = *result;
}
return heif_error_success;
@@ -193,23 +193,23 @@ heif_error heif_image_add_component(heif_image* image,
// --- untyped uint8 accessors
-const uint8_t* heif_image_get_component_readonly(const heif_image* image, uint32_t component_idx, size_t* out_stride)
+const uint8_t* heif_image_get_component_readonly(const heif_image* image, uint32_t component_id, size_t* out_stride)
{
if (!image || !image->image) {
if (out_stride) *out_stride = 0;
return nullptr;
}
- return image->image->get_component(component_idx, out_stride);
+ return image->image->get_component(component_id, out_stride);
}
-uint8_t* heif_image_get_component(heif_image* image, uint32_t component_idx, size_t* out_stride)
+uint8_t* heif_image_get_component(heif_image* image, uint32_t component_id, size_t* out_stride)
{
if (!image || !image->image) {
if (out_stride) *out_stride = 0;
return nullptr;
}
- return image->image->get_component(component_idx, out_stride);
+ return image->image->get_component(component_id, out_stride);
}
@@ -219,7 +219,7 @@ uint8_t* heif_image_get_component(heif_image* image, uint32_t component_idx, siz
// (<= 16 bytes), so the division is always exact.
#define heif_image_get_component_X(name, type) \
const type* heif_image_get_component_ ## name ## _readonly(const struct heif_image* image, \
- uint32_t component_idx, \
+ uint32_t component_id, \
size_t* out_row_elements) \
{ \
if (!image || !image->image) { \
@@ -227,13 +227,13 @@ const type* heif_image_get_component_ ## name ## _readonly(const struct heif_ima
return nullptr; \
} \
size_t byte_stride = 0; \
- const type* p = image->image->get_component_memory<type>(component_idx, &byte_stride); \
+ const type* p = image->image->get_component_memory<type>(component_id, &byte_stride); \
if (out_row_elements) *out_row_elements = byte_stride / sizeof(type); \
return p; \
} \
\
type* heif_image_get_component_ ## name (struct heif_image* image, \
- uint32_t component_idx, \
+ uint32_t component_id, \
size_t* out_row_elements) \
{ \
if (!image || !image->image) { \
@@ -241,7 +241,7 @@ type* heif_image_get_component_ ## name (struct heif_image* image, \
return nullptr; \
} \
size_t byte_stride = 0; \
- type* p = image->image->get_component_memory<type>(component_idx, &byte_stride); \
+ type* p = image->image->get_component_memory<type>(component_id, &byte_stride); \
if (out_row_elements) *out_row_elements = byte_stride / sizeof(type); \
return p; \
}
diff --git a/libheif/api/libheif/heif_components.h b/libheif/api/libheif/heif_components.h
index 8e472708..b9d78059 100644
--- a/libheif/api/libheif/heif_components.h
+++ b/libheif/api/libheif/heif_components.h
@@ -89,36 +89,36 @@ typedef enum heif_cmpd_component_type
} heif_cmpd_component_type;
-// --- index-based component access (operates on a decoded heif_image)
+// --- ID-based component access (operates on a decoded heif_image)
// Returns the number of components that have pixel data (planes) in this image.
LIBHEIF_API
uint32_t heif_image_get_number_of_used_components(const heif_image*);
-// Fills `out_component_indices` with the valid component indices.
+// Fills `out_component_ids` with the valid component IDs.
// The caller must allocate an array of at least heif_image_get_number_of_used_components() elements.
LIBHEIF_API
void heif_image_get_used_component_ids(const heif_image*, uint32_t* out_component_ids);
LIBHEIF_API
-heif_channel heif_image_get_component_channel(const heif_image*, uint32_t component_idx);
+heif_channel heif_image_get_component_channel(const heif_image*, uint32_t component_id);
LIBHEIF_API
-uint32_t heif_image_get_component_width(const heif_image*, uint32_t component_idx);
+uint32_t heif_image_get_component_width(const heif_image*, uint32_t component_id);
LIBHEIF_API
-uint32_t heif_image_get_component_height(const heif_image*, uint32_t component_idx);
+uint32_t heif_image_get_component_height(const heif_image*, uint32_t component_id);
LIBHEIF_API
-int heif_image_get_component_bits_per_pixel(const heif_image*, uint32_t component_idx);
+int heif_image_get_component_bits_per_pixel(const heif_image*, uint32_t component_id);
LIBHEIF_API
-uint16_t heif_image_get_component_type(const heif_image*, uint32_t component_idx);
+uint16_t heif_image_get_component_type(const heif_image*, uint32_t component_id);
// Returns the datatype (unsigned/signed integer, floating point, or complex
// number) of the given component.
LIBHEIF_API
-heif_component_datatype heif_image_get_component_datatype(const heif_image*, uint32_t component_idx);
+heif_component_datatype heif_image_get_component_datatype(const heif_image*, uint32_t component_id);
// --- ID-based component access via heif_image_handle (before decoding)
@@ -159,16 +159,16 @@ heif_error heif_image_add_component(heif_image* image,
uint16_t component_type,
heif_component_datatype datatype,
int bit_depth,
- uint32_t* out_component_idx);
+ uint32_t* out_component_id);
// --- untyped uint8 component data getters: stride is in BYTES per row.
LIBHEIF_API
-const uint8_t* heif_image_get_component_readonly(const heif_image*, uint32_t component_idx, size_t* out_stride);
+const uint8_t* heif_image_get_component_readonly(const heif_image*, uint32_t component_id, size_t* out_stride);
LIBHEIF_API
-uint8_t* heif_image_get_component(heif_image*, uint32_t component_idx, size_t* out_stride);
+uint8_t* heif_image_get_component(heif_image*, uint32_t component_id, size_t* out_stride);
// --- typed component data getters: `out_row_elements` is the number of T
@@ -177,70 +177,70 @@ uint8_t* heif_image_get_component(heif_image*, uint32_t component_idx, size_t* o
// this count is always exact for the named type T.
LIBHEIF_API
-const uint16_t* heif_image_get_component_uint16_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const uint16_t* heif_image_get_component_uint16_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-uint16_t* heif_image_get_component_uint16(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+uint16_t* heif_image_get_component_uint16(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const uint32_t* heif_image_get_component_uint32_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const uint32_t* heif_image_get_component_uint32_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-uint32_t* heif_image_get_component_uint32(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+uint32_t* heif_image_get_component_uint32(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const uint64_t* heif_image_get_component_uint64_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const uint64_t* heif_image_get_component_uint64_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-uint64_t* heif_image_get_component_uint64(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+uint64_t* heif_image_get_component_uint64(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const int8_t* heif_image_get_component_int8_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const int8_t* heif_image_get_component_int8_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-int8_t* heif_image_get_component_int8(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+int8_t* heif_image_get_component_int8(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const int16_t* heif_image_get_component_int16_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const int16_t* heif_image_get_component_int16_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-int16_t* heif_image_get_component_int16(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+int16_t* heif_image_get_component_int16(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const int32_t* heif_image_get_component_int32_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const int32_t* heif_image_get_component_int32_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-int32_t* heif_image_get_component_int32(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+int32_t* heif_image_get_component_int32(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const int64_t* heif_image_get_component_int64_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const int64_t* heif_image_get_component_int64_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-int64_t* heif_image_get_component_int64(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+int64_t* heif_image_get_component_int64(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const float* heif_image_get_component_float32_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const float* heif_image_get_component_float32_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-float* heif_image_get_component_float32(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+float* heif_image_get_component_float32(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const double* heif_image_get_component_float64_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const double* heif_image_get_component_float64_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-double* heif_image_get_component_float64(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+double* heif_image_get_component_float64(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const heif_complex32* heif_image_get_component_complex32_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const heif_complex32* heif_image_get_component_complex32_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-heif_complex32* heif_image_get_component_complex32(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+heif_complex32* heif_image_get_component_complex32(heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-const heif_complex64* heif_image_get_component_complex64_readonly(const heif_image*, uint32_t component_idx, size_t* out_row_elements);
+const heif_complex64* heif_image_get_component_complex64_readonly(const heif_image*, uint32_t component_id, size_t* out_row_elements);
LIBHEIF_API
-heif_complex64* heif_image_get_component_complex64(heif_image*, uint32_t component_idx, size_t* out_row_elements);
+heif_complex64* heif_image_get_component_complex64(heif_image*, uint32_t component_id, size_t* out_row_elements);
// --- GIMI component content IDs (set before encoding)