1 /*
2 ** SPDX-License-Identifier: BSD-3-Clause
3 ** Copyright Contributors to the OpenEXR Project.
4 */
5 
6 #ifndef OPENEXR_INTERNAL_ATTR_H
7 #define OPENEXR_INTERNAL_ATTR_H
8 
9 #include "openexr_attr.h"
10 #include "openexr_context.h"
11 
12 /**
13  * @defgroup InternalAttributeFunctions Functions for manipulating attributes
14  *
15  * The functions are currently internal to the library and are not
16  * exposed to the outside. This is done primarily to strengthen the
17  * contract around const-ness which then implies when it is safe (or
18  * not) to use an exr context in a threaded manner.
19  *
20  * NB: These functions are not tagged with internal_ as a prefix like
21  * other internal functions are such that if it is deemed useful to
22  * expose them publicly in the future, it is easier to do so.
23  *
24  * @{
25  * @}
26  */
27 
28 #include "internal_channel_list.h"
29 #include "internal_float_vector.h"
30 #include "internal_opaque.h"
31 #include "internal_preview.h"
32 #include "internal_string.h"
33 #include "internal_string_vector.h"
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 int internal_exr_is_standard_type (const char* typen);
40 
41 /** @addtogroup InternalAttributeFunctions
42  * @{
43  */
44 
45 typedef struct exr_attribute_list
46 {
47     int num_attributes; /**< Number of attribute entries in the list */
48     int num_alloced; /**< Allocation count. if > 0, attribute list owns pointer */
49     exr_attribute_t** entries; /**< Creation order list of attributes */
50     exr_attribute_t**
51         sorted_entries; /**< Sorted order list of attributes for fast lookup */
52 } exr_attribute_list_t;
53 
54 /** Initialize a list to an empty attribute list */
55 exr_result_t exr_attr_list_init (exr_context_t ctxt, exr_attribute_list_t* l);
56 
57 /** Free memory for all the owned attributes in the list as well as the list itself */
58 exr_result_t
59 exr_attr_list_destroy (exr_context_t ctxt, exr_attribute_list_t* l);
60 
61 /** Compute the number of bytes required to store this attribute list in a file */
62 exr_result_t exr_attr_list_compute_size (
63     exr_context_t ctxt, exr_attribute_list_t* l, uint64_t* out);
64 
65 /** Find an attribute in the list by name */
66 exr_result_t exr_attr_list_find_by_name (
67     exr_const_context_t   ctxt,
68     exr_attribute_list_t* l,
69     const char*           name,
70     exr_attribute_t**     out);
71 
72 /** @brief Adds a new attribute to the list with a name and a (string) type
73  *
74  * if data_len > 0, will allocate extra memory as part of the
75  * attribute block which allows one to do things like pre-allocate the
76  * string storage space for a string attribute, or similar. If this is
77  * specified, data_ptr must be provided to receive the memory
78  * location. The responsibility is transferred to the caller to know
79  * not to free this returned memory.
80  *
81  */
82 exr_result_t exr_attr_list_add_by_type (
83     exr_context_t         ctxt,
84     exr_attribute_list_t* l,
85     const char*           name,
86     const char*           type,
87     int32_t               data_len,
88     uint8_t**             data_ptr,
89     exr_attribute_t**     attr);
90 
91 /** @brief Adds a new attribute to the list with a name and a built-in type
92  *
93  * if data_len > 0, will allocate extra memory as part of the
94  * attribute block which allows one to do things like pre-allocate the
95  * string storage space for a string attribute, or similar. If this is
96  * specified, data_ptr must be provided to receive the memory
97  * location. The responsibility is transferred to the caller to know
98  * not to free this returned memory.
99  *
100  */
101 exr_result_t exr_attr_list_add (
102     exr_context_t         ctxt,
103     exr_attribute_list_t* l,
104     const char*           name,
105     exr_attribute_type_t  type,
106     int32_t               data_len,
107     uint8_t**             data_ptr,
108     exr_attribute_t**     attr);
109 
110 /** @brief Adds a new attribute to the list with a static name (no
111  * allocation) and a built-in type
112  *
113  * if data_len > 0, will allocate extra memory as part of the
114  * attribute block which allows one to do things like pre-allocate the
115  * string storage space for a string attribute, or similar. If this is
116  * specified, data_ptr must be provided to receive the memory
117  * location. The responsibility is transferred to the caller to know
118  * not to free this returned memory.
119  *
120  */
121 exr_result_t exr_attr_list_add_static_name (
122     exr_context_t         ctxt,
123     exr_attribute_list_t* l,
124     const char*           name,
125     exr_attribute_type_t  type,
126     int32_t               data_len,
127     uint8_t**             data_ptr,
128     exr_attribute_t**     attr);
129 
130 /** Removes an attribute from the list and frees any associated memory */
131 exr_result_t exr_attr_list_remove (
132     exr_context_t ctxt, exr_attribute_list_t* l, exr_attribute_t* attr);
133 
134 /**
135  * @}
136  */
137 
138 #ifdef __cplusplus
139 } /* extern "C" */
140 #endif
141 
142 #endif /* OPENEXR_INTERNAL_ATTR_H */
143