202 lines
6.4 KiB
C
202 lines
6.4 KiB
C
/*
|
|
** SPDX-License-Identifier: BSD-3-Clause
|
|
** Copyright Contributors to the OpenEXR Project.
|
|
*/
|
|
|
|
#ifndef OPENEXR_BASE_H
|
|
#define OPENEXR_BASE_H
|
|
|
|
#include "openexr_config.h"
|
|
|
|
#include <stddef.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** @file */
|
|
|
|
/** @brief Retrieve the current library version. The @p extra string is for
|
|
* custom installs, and is a static string, do not free the returned
|
|
* pointer.
|
|
*/
|
|
EXR_EXPORT void
|
|
exr_get_library_version (int* maj, int* min, int* patch, const char** extra);
|
|
|
|
/**
|
|
* @defgroup SafetyChecks Controls for internal safety checks
|
|
* @{
|
|
*/
|
|
|
|
/** @brief Limit the size of image allowed to be parsed or created by
|
|
* the library.
|
|
*
|
|
* This is used as a safety check against corrupt files, but can also
|
|
* serve to avoid potential issues on machines which have very
|
|
* constrained RAM.
|
|
*
|
|
* These values are among the only globals in the core layer of
|
|
* OpenEXR. The intended use is for applications to define a global
|
|
* default, which will be combined with the values provided to the
|
|
* individual context creation routine. The values are used to check
|
|
* against parsed header values. This adds some level of safety from
|
|
* memory overruns where a corrupt file given to the system may cause
|
|
* a large allocation to happen, enabling buffer overruns or other
|
|
* potential security issue.
|
|
*
|
|
* These global values are combined with the values in
|
|
* \ref exr_context_initializer_t using the following rules:
|
|
*
|
|
* 1. negative values are ignored.
|
|
*
|
|
* 2. if either value has a positive (non-zero) value, and the other
|
|
* has 0, the positive value is preferred.
|
|
*
|
|
* 3. If both are positive (non-zero), the minimum value is used.
|
|
*
|
|
* 4. If both values are 0, this disables the constrained size checks.
|
|
*
|
|
* This function does not fail.
|
|
*/
|
|
EXR_EXPORT void exr_set_default_maximum_image_size (int w, int h);
|
|
|
|
/** @brief Retrieve the global default maximum image size.
|
|
*
|
|
* This function does not fail.
|
|
*/
|
|
EXR_EXPORT void exr_get_default_maximum_image_size (int* w, int* h);
|
|
|
|
/** @brief Limit the size of an image tile allowed to be parsed or
|
|
* created by the library.
|
|
*
|
|
* Similar to image size, this places constraints on the maximum tile
|
|
* size as a safety check against bad file data
|
|
*
|
|
* This is used as a safety check against corrupt files, but can also
|
|
* serve to avoid potential issues on machines which have very
|
|
* constrained RAM
|
|
*
|
|
* These values are among the only globals in the core layer of
|
|
* OpenEXR. The intended use is for applications to define a global
|
|
* default, which will be combined with the values provided to the
|
|
* individual context creation routine. The values are used to check
|
|
* against parsed header values. This adds some level of safety from
|
|
* memory overruns where a corrupt file given to the system may cause
|
|
* a large allocation to happen, enabling buffer overruns or other
|
|
* potential security issue.
|
|
*
|
|
* These global values are combined with the values in
|
|
* \ref exr_context_initializer_t using the following rules:
|
|
*
|
|
* 1. negative values are ignored.
|
|
*
|
|
* 2. if either value has a positive (non-zero) value, and the other
|
|
* has 0, the positive value is preferred.
|
|
*
|
|
* 3. If both are positive (non-zero), the minimum value is used.
|
|
*
|
|
* 4. If both values are 0, this disables the constrained size checks.
|
|
*
|
|
* This function does not fail.
|
|
*/
|
|
EXR_EXPORT void exr_set_default_maximum_tile_size (int w, int h);
|
|
|
|
/** @brief Retrieve the global maximum tile size.
|
|
*
|
|
* This function does not fail.
|
|
*/
|
|
EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup CompressionDefaults Provides default compression settings
|
|
* @{
|
|
*/
|
|
|
|
/** @brief Assigns a default zip compression level.
|
|
*
|
|
* This value may be controlled separately on each part, but this
|
|
* global control determines the initial value.
|
|
*/
|
|
EXR_EXPORT void exr_set_default_zip_compression_level (int l);
|
|
|
|
/** @brief Retrieve the global default zip compression value
|
|
*/
|
|
EXR_EXPORT void exr_get_default_zip_compression_level (int* l);
|
|
|
|
/** @brief Assigns a default DWA compression quality level.
|
|
*
|
|
* This value may be controlled separately on each part, but this
|
|
* global control determines the initial value.
|
|
*/
|
|
EXR_EXPORT void exr_set_default_dwa_compression_quality (float q);
|
|
|
|
/** @brief Retrieve the global default dwa compression quality
|
|
*/
|
|
EXR_EXPORT void exr_get_default_dwa_compression_quality (float* q);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup MemoryAllocators Provides global control over memory allocators
|
|
* @{
|
|
*/
|
|
|
|
/** @brief Function pointer used to hold a malloc-like routine.
|
|
*
|
|
* Providing these to a context will override what memory is used to
|
|
* allocate the context itself, as well as any allocations which
|
|
* happen during processing of a file or stream. This can be used by
|
|
* systems which provide rich malloc tracking routines to override the
|
|
* internal allocations performed by the library.
|
|
*
|
|
* This function is expected to allocate and return a new memory
|
|
* handle, or `NULL` if allocation failed (which the library will then
|
|
* handle and return an out-of-memory error).
|
|
*
|
|
* If one is provided, both should be provided.
|
|
* @sa exr_memory_free_func_t
|
|
*/
|
|
typedef void* (*exr_memory_allocation_func_t) (size_t bytes);
|
|
|
|
/** @brief Function pointer used to hold a free-like routine.
|
|
*
|
|
* Providing these to a context will override what memory is used to
|
|
* allocate the context itself, as well as any allocations which
|
|
* happen during processing of a file or stream. This can be used by
|
|
* systems which provide rich malloc tracking routines to override the
|
|
* internal allocations performed by the library.
|
|
*
|
|
* This function is expected to return memory to the system, ala free
|
|
* from the C library.
|
|
*
|
|
* If providing one, probably need to provide both routines.
|
|
* @sa exr_memory_allocation_func_t
|
|
*/
|
|
typedef void (*exr_memory_free_func_t) (void* ptr);
|
|
|
|
/** @brief Allow the user to override default allocator used internal
|
|
* allocations necessary for files, attributes, and other temporary
|
|
* memory.
|
|
*
|
|
* These routines may be overridden when creating a specific context,
|
|
* however this provides global defaults such that the default can be
|
|
* applied.
|
|
*
|
|
* If either pointer is 0, the appropriate malloc/free routine will be
|
|
* substituted.
|
|
*
|
|
* This function does not fail.
|
|
*/
|
|
EXR_EXPORT void exr_set_default_memory_routines (
|
|
exr_memory_allocation_func_t alloc_func, exr_memory_free_func_t free_func);
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#endif /* OPENEXR_BASE_H */
|