#include <cstdint>
#include <memory>
#include <stdexcept>
#include <sys/stat.h>
#include <unistd.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <filesystem>
#include <mutex>
#include "grk_fseek.h"
#include "TFSingleton.h"
#include "MinHeap.h"
#include "SequentialCache.h"
#include "SparseCache.h"
#include "CodeStreamLimits.h"
#include "geometry.h"
#include "MemManager.h"
#include "buffer.h"
#include "ChunkBuffer.h"
#include "minpf_plugin_manager.h"
#include "plugin_interface.h"
#include "plugin_gpup_bridge.h"
#include "TileWindow.h"
#include "GrkObjectWrapper.h"
#include "ChronoTimer.h"
#include "testing.h"
#include "MappedFile.h"
#include "GrkMatrix.h"
#include "Quantizer.h"
#include "SparseBuffer.h"
#include "ResSimple.h"
#include "SparseCanvas.h"
#include "intmath.h"
#include "ImageComponentFlow.h"
#include "TileFutureManager.h"
#include "MarkerCache.h"
#include "SlabPool.h"
#include "StreamIO.h"
#include "IStream.h"
#include "MemAdvisor.h"
#include "FetchCommon.h"
#include "TPFetchSeq.h"
#include "GrkImage.h"
#include "ICompressor.h"
#include "IDecompressor.h"
#include "MemStream.h"
#include "StreamGenerator.h"
#include "Profile.h"
#include "MarkerParser.h"
#include "Codec.h"
#include "GrkImageSIMD.h"
#include "PLMarker.h"
#include "SIZMarker.h"
#include "PPMMarker.h"
#include "PacketParser.h"
#include "PacketCache.h"
#include "CodingParams.h"
#include "CodeStream.h"
#include "PacketIter.h"
#include "PacketLengthCache.h"
#include "TLMMarker.h"
#include "ICoder.h"
#include "CoderPool.h"
#include "FileFormatJP2Family.h"
#include "FileFormatJP2Compress.h"
#include "FileFormatJP2Decompress.h"
#include "FileFormatMJ2.h"
#include "FileFormatMJ2Compress.h"
#include "FileFormatMJ2Decompress.h"
#include "BitIO.h"
#include "TagTree.h"
#include "Codeblock.h"
#include "CodeblockCompress.h"
#include "CodeblockDecompress.h"
#include "Precinct.h"
#include "Subband.h"
#include "Resolution.h"
#include "BlockExec.h"
#include "CodecScheduler.h"
#include "TileComponentWindow.h"
#include "ITileProcessor.h"
#include "ITileProcessorCompress.h"
#include "SOTMarker.h"
#include "CodeStreamCompress.h"
#include "TileCache.h"
#include "TileCompletion.h"
#include "CodeStreamDecompress.h"

Classes
class	GrkCleanup
struct	InitState

Namespaces
namespace	grk
	ResWindow.

Functions
static void	infoCallback (const char msg, void client_data)
static void	debugCallback (const char msg, void client_data)
static void	traceCallback (const char msg, void client_data)
static void	warningCallback (const char msg, void client_data)
static void	errorCallback (const char msg, void client_data)
static grk_object *	grkDecompressCreate (grk::IStream *stream)
void	grk_deinitialize (void)
	Deinitialize the Grok library.
void *	grk_thread_pool (void)
	Returns an opaque handle to the core thread-pool executor.
size_t	grk_num_workers (void)
	Returns the number of worker threads in the core thread pool.
uint32_t	grk_worker_id (void)
	Returns the TaskFlow worker id of the calling thread.
static bool	areStringsEqual (const char lhs, const char rhs)
void	grk_initialize (const char pluginPath, uint32_t numThreads, bool plugin_initialized)
	Initializes the Grok library.
GRK_API grk_object *GRK_CALLCONV	grk_object_ref (grk_object *obj)
	Increments the reference count on a Grok object.
GRK_API void GRK_CALLCONV	grk_object_unref (grk_object *obj)
	Decrements the reference count on a Grok object.
GRK_API void GRK_CALLCONV	grk_set_msg_handlers (grk_msg_handlers msg_handlers)
	Installs application-defined log message handlers.
const char *	grk_version (void)
	Gets the Grok library version string.
bool	grk_detect_format (const char file_path, GRK_CODEC_FORMAT format)
	Detect the JPEG 2000 codec format of a file by reading its magic bytes.
grk_image *	grk_image_new (uint16_t numcmpts, grk_image_comp *cmptparms, GRK_COLOR_SPACE clrspc, bool alloc_data)
	Allocates a new Grok image with the specified component layout.
grk_data_type	grk_get_data_type (bool compress, uint8_t prec, bool is_mct, uint8_t qmfbid, bool fast_mct)
	Determine the data type used by Grok for image component data.
grk_image_meta *	grk_image_meta_new (void)
	Allocates an empty image metadata object.
static bool	resolve_meta_field (grk_image_meta meta, const char field, uint8_t *buf_pp, size_t len_pp)
bool	grk_image_meta_set_field (grk_image_meta meta, const char field, const uint8_t *data, size_t len)
	Set a metadata buffer on a grk_image_meta object.
bool	grk_image_meta_get_field (grk_image_meta meta, const char field, uint8_t *data, size_t len)
	Get a metadata buffer from a grk_image_meta object.
bool	grk_image_meta_set_asocs (grk_image_meta meta, const grk_asoc asocs, uint32_t num_asocs)
	Set association boxes on a grk_image_meta object for writing.
grk_object *	grk_decompress_init (grk_stream_params streamParams, grk_decompress_parameters decompressParams)
	Creates and initializes a JPEG 2000 decompressor.
grk_progression_state	grk_decompress_get_progression_state (grk_object *codec, uint16_t tile_index)
	Retrieves the current progression state for a cached tile.
GRK_API bool GRK_CALLCONV	grk_decompress_set_progression_state (grk_object *codec, grk_progression_state state)
	Applies a new progression state to one or all cached tiles.
bool	grk_decompress_update (grk_decompress_parameters params, grk_object codec)
	Updates decompression parameters on an already-initialized codec.
bool	grk_decompress_read_header (grk_object codecWrapper, grk_header_info header_info)
	Reads and parses the JPEG 2000 image header.
void	grk_decompress_wait (grk_object codecWrapper, grk_wait_swath swath)
	Waits for an asynchronous decompression to complete.
void	grk_decompress_schedule_swath_copy (grk_object codecWrapper, const grk_wait_swath swath, grk_swath_buffer *buf)
	Schedule tile-to-swath copies for a completed swath.
void	grk_decompress_wait_swath_copy (grk_object *codecWrapper)
	Wait for all in-flight swath copy tasks to complete.
void	grk_copy_tile_to_swath (const grk_image tile_img, const grk_swath_buffer buf)
	Copy a single decoded tile image into a swath buffer using Highway SIMD.
bool	grk_decompress (grk_object codecWrapper, grk_plugin_tile tile)
	Starts (or continues) decompression of the JPEG 2000 image.
bool	grk_decompress_tile (grk_object *codecWrapper, uint16_t tile_index)
	Decompresses a single tile by index.
uint32_t	grk_decompress_num_samples (grk_object *codecWrapper)
	Gets the number of samples (frames) in the codec container.
bool	grk_decompress_sample (grk_object *codecWrapper, uint32_t sample_index)
	Decompresses a single sample (frame) by index.
grk_image *	grk_decompress_get_sample_image (grk_object *codecWrapper, uint32_t sample_index)
	Gets the decompressed image for a specific sample (frame).
grk_image *	grk_decompress_get_sample_tile_image (grk_object *codecWrapper, uint32_t sample_index, uint16_t tile_index)
	Gets a decompressed tile image from a specific sample (frame).
void	grk_dump_codec (grk_object codecWrapper, uint32_t info_flag, FILE output_stream)
	Dumps codec diagnostic information to a stream.
bool	grk_set_MCT (grk_cparameters parameters, const float pEncodingMatrix, const int32_t *p_dc_shift, uint32_t pNbComp)
	Installs a custom Multi-Component Transform (MCT) matrix.
grk_image *	grk_decompress_get_tile_image (grk_object *codecWrapper, uint16_t tile_index, bool wait)
	Gets decompressed tile image by tile index.
grk_image *	grk_decompress_get_image (grk_object *codecWrapper)
	Gets the composite decompressed image.
void	grk_decompress_set_band_callback (grk_object codecWrapper, grk_io_band_callback callback, void user_data)
	Set a band-completion callback on the decompressor.
bool	grk_image_is_post_process_no_op (grk_image *image)
	Checks whether the image requires post-processing (palette, ICC, colour space conversion, precision override, or upsampling).
static bool	grkStartCompress (grk_object *codecWrapper)
	Starts compressing image.
grk_object *	grk_compress_create (GRK_CODEC_FORMAT p_format, grk::IStream *stream)
void	grk_compress_set_default_params (grk_cparameters *parameters)
	Fills a grk_cparameters struct with safe default values.
grk_object *	grk_compress_init (grk_stream_params streamParams, grk_cparameters parameters, grk_image *image)
	Creates and initializes a JPEG 2000 compressor.
uint64_t	grk_compress (grk_object codecWrapper, grk_plugin_tile tile)
	Compresses the image into a JPEG 2000 codestream.
uint64_t	grk_compress_frame (grk_object codecWrapper, grk_image image, grk_plugin_tile *tile)
	Compresses an additional frame into a multi-frame container (MJ2).
bool	grk_compress_finish (grk_object *codecWrapper)
	Finalizes a multi-frame compress container (e.g.
uint64_t	grk_compress_get_compressed_length (grk_object *codecWrapper)
	Gets the total compressed length (bytes written to output stream/buffer).
uint64_t	grk_transcode (grk_stream_params srcStream, grk_stream_params dstStream, grk_cparameters parameters, grk_image image)
	Transcodes a JPEG 2000 file by rewriting JP2 boxes while copying the codestream verbatim.
bool	grk_plugin_load (grk_plugin_load_info info)
	Loads a hardware-accelerator plugin (.so / .dll).
uint32_t	grk_plugin_get_debug_state ()
	Returns the current debug state bitmask of the loaded plugin.
void	grk_plugin_cleanup (void)
	Unloads the plugin and releases all plugin-owned resources.
GRK_API bool GRK_CALLCONV	grk_plugin_init (grk_plugin_init_info initInfo)
	Initializes a loaded plugin with a device and license.
uint64_t	grk_plugin_internal_encode_callback (gpup_compress_callback_info *info)
int32_t	grk_plugin_compress (grk_cparameters *compress_parameters, GRK_PLUGIN_COMPRESS_USER_CALLBACK callback)
	Compresses a single image using the loaded hardware plugin.
int32_t	grk_plugin_batch_compress (grk_plugin_compress_batch_info info)
	Compresses a directory of images in batch using the hardware plugin.
GRK_API void GRK_CALLCONV	grk_plugin_wait_for_batch_complete (void)
	Blocks until all pending plugin batch jobs have completed.
void	grk_plugin_stop_batch_compress (void)
	Requests cancellation of a running batch compress operation.
static int	grk_to_gpup_init_decompressors_bridge (grk_header_info hdr, grk_image img)
int32_t	grk_plugin_internal_decode_callback (PluginDecodeCallbackInfo *info)
int32_t	grk_plugin_decompress (grk_decompress_parameters *decompress_parameters, grk_plugin_decompress_callback callback)
	Decompresses a single JPEG 2000 image using the loaded hardware plugin.
int32_t	grk_plugin_init_batch_decompress (const char input_dir, const char output_dir, grk_decompress_parameters *decompress_parameters, grk_plugin_decompress_callback callback)
	Initialises a batch plugin decompress operation but does not start it.
int32_t	grk_plugin_batch_decompress (void)
	Starts (resumes) the queued batch decompress operation.
void	grk_plugin_stop_batch_decompress (void)
	Requests cancellation of a running batch decompress operation.

Variables
static InitState	initState_
static std::mutex	initMutex
static const char *	plugin_get_debug_state_method_name = "plugin_get_debug_state"
static const char *	plugin_init_method_name = "plugin_init"
static const char *	plugin_encode_method_name = "plugin_encode"
static const char *	plugin_batch_encode_method_name = "plugin_batch_encode"
static const char *	plugin_stop_batch_encode_method_name = "plugin_stop_batch_encode"
static const char *	plugin_wait_for_batch_complete_method_name = "plugin_wait_for_batch_complete"
static const char *	plugin_decode_method_name = "plugin_decompress"
static const char *	plugin_init_batch_decode_method_name = "plugin_init_batch_decompress"
static const char *	plugin_batch_decode_method_name = "plugin_batch_decompress"
static const char *	plugin_stop_batch_decode_method_name = "plugin_stop_batch_decompress"
bool	pluginLoaded = false
GRK_PLUGIN_COMPRESS_USER_CALLBACK	userEncodeCallback = 0
static grk_cparameters *	s_originalCompressParams = nullptr
PLUGIN_WAIT_FOR_BATCH_COMPLETE	funcPluginWaitForBatchComplete = nullptr
grk_plugin_decompress_callback	decodeCallback = 0
static grk_decompress_parameters *	s_originalDecompressParams = nullptr
static GPUP_INIT_DECOMPRESSORS	s_gpupInitDecompressorsFn = nullptr

Function Documentation

◆ areStringsEqual()

bool areStringsEqual	(	const char *	lhs,
		const char *	rhs )

inlinestatic

Referenced by InitState::operator==().

◆ debugCallback()

void debugCallback	(	const char *	msg,
		void *	client_data )

static

Referenced by grk_initialize().

◆ errorCallback()

void errorCallback	(	const char *	msg,
		void *	client_data )

static

Referenced by grk_initialize().

◆ grk_compress()

uint64_t grk_compress	(	grk_object *	codec,
		grk_plugin_tile *	tile )

Compresses the image into a JPEG 2000 codestream.

Performs the full encode pipeline (MCT, DWT, T1, rate control, T2) and writes the result to the output stream supplied to grk_compress_init().

The tile parameter is only used when a hardware-accelerator plugin performs some encoding stages; pass NULL for CPU-only encoding.

Parameters

codec	compression codec (see grk_object)
tile	plugin tile data, or NULL for CPU-only encoding (see grk_plugin_tile)

Returns: number of bytes written to the output stream, or 0 on failure

References grk::Codec::getImpl(), and grk_initialize().

◆ grk_compress_create()

grk_object * grk_compress_create	(	GRK_CODEC_FORMAT	p_format,
		grk::IStream *	stream )

References grk::Codec::compressor_, GRK_CODEC_J2K, GRK_CODEC_JP2, GRK_CODEC_MJ2, and grk::Codec::obj.

Referenced by grk_compress_init(), and grk_transcode().

◆ grk_compress_finish()

bool grk_compress_finish ( grk_object * codec )

Finalizes a multi-frame compress container (e.g.

writes MJ2 moov box). For single-image formats this is a no-op.

Parameters

codec compression codec (see grk_object)

Returns: true if successful, otherwise false

References grk::Codec::getImpl().

◆ grk_compress_frame()

uint64_t grk_compress_frame	(	grk_object *	codec,
		grk_image *	image,
		grk_plugin_tile *	tile )

Compresses an additional frame into a multi-frame container (MJ2).

For single-image formats (JP2, J2K) this returns 0 (unsupported).

Parameters

codec	compression codec (see grk_object)
image	Input image for this frame (see grk_image)
tile	plugin tile (see grk_plugin_tile)

Returns: number of bytes written if successful, 0 otherwise

References grk::Codec::getImpl().

◆ grk_compress_get_compressed_length()

uint64_t grk_compress_get_compressed_length ( grk_object * codec )

Gets the total compressed length (bytes written to output stream/buffer).

Parameters

codec compression codec (see grk_object)

Returns: compressed length in bytes, or 0 on failure

References grk::Codec::getImpl().

◆ grk_compress_init()

grk_object * grk_compress_init	(	grk_stream_params *	stream_params,
		grk_cparameters *	parameters,
		grk_image *	image )

Creates and initializes a JPEG 2000 compressor.

Allocates and prepares all compression state for the provided image. The output destination (file, buffer, or callbacks) is described by stream_params. Encoding parameters (tile size, DWT levels, quality layers, etc.) are taken from parameters — call grk_compress_set_default_params() first to populate defaults.

The image must remain valid until grk_compress() completes. The returned codec object must be released with grk_object_unref().

Parameters

stream_params	output stream description (see grk_stream_params)
parameters	compression settings (see grk_cparameters)
image	source image to compress (see grk_image)

Returns: pointer to an opaque grk_object on success, NULL on failure (invalid parameters, unsupported image, OOM)

References grk::StreamGenerator::create(), grk::Codec::getImpl(), GRK_CODEC_J2K, GRK_CODEC_JP2, GRK_CODEC_MJ2, grk_compress_create(), GRK_FMT_J2K, GRK_FMT_JP2, GRK_FMT_MJ2, grk_object_unref(), grk::grklog, and grkStartCompress().

◆ grk_compress_set_default_params()

void grk_compress_set_default_params ( grk_cparameters * parameters )

Fills a grk_cparameters struct with safe default values.

Defaults applied:

No rate constraints (lossless)
Tile size: entire image (single tile)
Codeblock size: 64×64
Precinct size: 2^15×2^15 (effectively no sub-precincts)
Number of DWT resolutions: 6
1 quality layer
No SOP / EPH markers
No ROI upshift
No mode switches (no LAZY, RESET, etc.)
Progression order: LRCP
Reversible 5-3 DWT
Multi-component transform enabled (when 3+ components present)
Image origin (0,0); tile origin (0,0); no POC
Sub-sampling: dx=1, dy=1

Parameters

parameters compression parameter block to initialise (see grk_cparameters); must not be NULL

References grk::GRK_COMP_PARAM_DEFAULT_CBLOCKH, grk::GRK_COMP_PARAM_DEFAULT_CBLOCKW, grk::GRK_DEFAULT_NUMRESOLUTION, grk::GRK_DEFAULT_PROG_ORDER, GRK_FMT_UNK, GRK_PROFILE_NONE, and GRK_PROG_UNKNOWN.

◆ grk_copy_tile_to_swath()

void grk_copy_tile_to_swath	(	const grk_image *	tile_img,
		const grk_swath_buffer *	buf )

Copy a single decoded tile image into a swath buffer using Highway SIMD.

A low-level, synchronous alternative to grk_decompress_schedule_swath_copy() for callers that manage their own threading. Copies the source component data from tile_img into buf, clipping to buf's x/y window, applying band_map re-ordering, alpha promotion, and type conversion (int32 → prec/sgnd).

Thread-safe: multiple tiles may be copied into the same buf concurrently provided they write to non-overlapping output regions.

Parameters

tile_img	tile image returned by grk_decompress_get_tile_image()
buf	output swath buffer (must be pre-allocated and fully populated)

References grk::hwy_copy_tile_to_swath().

◆ grk_decompress()

bool grk_decompress	(	grk_object *	codec,
		grk_plugin_tile *	tile )

Starts (or continues) decompression of the JPEG 2000 image.

For synchronous decoding (asynchronous = false): blocks until all requested tiles are decompressed. After return, component data is available via grk_decompress_get_image() or grk_decompress_get_tile_image().

For asynchronous decoding (asynchronous = true): returns immediately after scheduling decompression tasks on the Taskflow executor. Use grk_decompress_wait() to synchronize on individual swath regions, and grk_decompress_schedule_swath_copy() + grk_decompress_wait_swath_copy() to copy decoded data into an output buffer.

The tile parameter is only used when integrating a hardware- accelerator plugin; pass NULL for CPU-only decoding.

Parameters

codec	decompression codec (see grk_object)
tile	plugin tile data, or NULL for CPU-only decoding (see grk_plugin_tile)

Returns: true if successful (sync) or if scheduling succeeded (async)

References grk::Codec::getImpl(), and grk_initialize().

Referenced by grk::FileFormatJP2Compress::transcodeCodestream().

◆ grk_decompress_get_image()

grk_image * grk_decompress_get_image ( grk_object * codec )

Gets the composite decompressed image.

Returns the composited output image (all tiles merged). Only valid after full decompression completes (grk_decompress_wait with null swath). Requires skip_allocate_composite=false in decompress parameters for data to be present. For per-tile access, prefer grk_decompress_get_tile_image() instead.

Parameters

codec decompression codec (see grk_object)

Returns: pointer to grk_image

References grk::Codec::getImpl().

◆ grk_decompress_get_progression_state()

grk_progression_state grk_decompress_get_progression_state	(	grk_object *	codec,
		uint16_t	tile_index )

Retrieves the current progression state for a cached tile.

A progression state describes how many quality layers have been decoded for each resolution level in a given tile. This is used to implement incremental / partial-quality decompression: decode a tile at reduced quality, inspect it, then decode more layers on demand.

Returns a zero-initialised struct if the tile has not been decompressed yet or is not in the tile cache.

Parameters

codec	decompression codec (see grk_object)
tile_index	zero-based tile index (row-major within the tile grid)

Returns: current grk_progression_state for the tile; all-zeros if the tile has not been decoded

References grk::Codec::getImpl().

◆ grk_decompress_get_sample_image()

grk_image * grk_decompress_get_sample_image	(	grk_object *	codec,
		uint32_t	sample_index )

Gets the decompressed image for a specific sample (frame).

Parameters

codec	decompression codec (see grk_object)
sample_index	sample index (0-based)

Returns: pointer to grk_image, or NULL if sample not decompressed

References grk::Codec::getImpl().

◆ grk_decompress_get_sample_tile_image()

grk_image * grk_decompress_get_sample_tile_image	(	grk_object *	codec,
		uint32_t	sample_index,
		uint16_t	tile_index )

Gets a decompressed tile image from a specific sample (frame).

Useful for multi-frame containers (MJ2) where each frame may have multiple tiles. The sample must have been decompressed first via grk_decompress() (for sample 0) or grk_decompress_sample() (for subsequent samples).

Parameters

codec	decompression codec (see grk_object)
sample_index	sample index (0-based)
tile_index	tile index within the sample (row-major)

Returns: pointer to grk_image for the tile, or NULL if not available

References grk::Codec::getImpl().

◆ grk_decompress_get_tile_image()

grk_image * grk_decompress_get_tile_image	(	grk_object *	codec,
		uint16_t	tile_index,
		bool	wait )

Gets decompressed tile image by tile index.

Returns per-tile decoded data after decompression completes. Works for both single-tile and multi-tile images. The tile index is: tile_y * num_tile_cols + tile_x (use grk_wait_swath output fields to compute).

Parameters

codec	decompression codec (see grk_object)
tile_index	tile index (row-major within the image tile grid)
wait	if true, block until the specified tile is decompressed

Returns: pointer to grk_image for the tile, or NULL if tile not available

References grk::Codec::getImpl().

◆ grk_decompress_init()

grk_object * grk_decompress_init	(	grk_stream_params *	stream_params,
		grk_decompress_parameters *	params )

Creates and initializes a JPEG 2000 decompressor.

Opens the source stream and reads enough of the header to determine the codec type (J2K codestream or JP2 file-format). The returned object holds all decompressor state and must be released with grk_object_unref() when the caller is done with it.

This function does NOT read the full image header; call grk_decompress_read_header() next to populate grk_header_info.

Parameters

stream_params	input stream description (file path, buffer, or callbacks — see grk_stream_params)
params	decompression options (tile range, window region, async mode, etc. — see grk_decompress_parameters)

Returns: pointer to an opaque grk_object on success, NULL on failure (bad stream, unsupported format, OOM)

References grk::StreamGenerator::create(), grk::Codec::getImpl(), grk_object_unref(), grkDecompressCreate(), and grk::grklog.

Referenced by grk::FileFormatJP2Compress::transcodeCodestream().

◆ grk_decompress_num_samples()

uint32_t grk_decompress_num_samples ( grk_object * codec )

Gets the number of samples (frames) in the codec container.

For single-image formats (JP2, J2K) this returns 1. For multi-frame formats (MJ2) this returns the number of video samples.

Parameters

codec decompression codec (see grk_object)

Returns: number of samples

References grk::Codec::getImpl().

◆ grk_decompress_read_header()

bool grk_decompress_read_header	(	grk_object *	codec,
		grk_header_info *	header_info )

Reads and parses the JPEG 2000 image header.

Must be called after grk_decompress_init() and before grk_decompress(). Populates header_info with image dimensions, tile grid, component descriptions, color space, bit-depths, ICC profile pointer, and progression/quality layer counts.

For asynchronous decoding: the image dimensions reported here reflect the full unscaled image; the async scheduler uses them when computing tile ranges for grk_decompress_wait().

Parameters

codec	decompression codec (see grk_object)
header_info	caller-allocated struct to receive header data (see grk_header_info); may be NULL if the caller only needs to prime the codec for grk_decompress()

Returns: true if the codestream main header (and JP2 superbox, if present) were read successfully; false on I/O or parse error

References grk::Codec::getImpl().

Referenced by grk::FileFormatJP2Compress::transcodeCodestream().

◆ grk_decompress_sample()

bool grk_decompress_sample	(	grk_object *	codec,
		uint32_t	sample_index )

Decompresses a single sample (frame) by index.

Parameters

codec	decompression codec (see grk_object)
sample_index	sample index (0-based)

Returns: true if successful, otherwise false

References grk::Codec::getImpl().

◆ grk_decompress_schedule_swath_copy()

void grk_decompress_schedule_swath_copy	(	grk_object *	codec,
		const grk_wait_swath *	swath,
		grk_swath_buffer *	buf )

Schedule tile-to-swath copies for a completed swath.

Call after grk_decompress_wait() returns for the given swath. For each tile in the swath, a Taskflow task is submitted to the library executor that converts the internal int32_t planar tile data into the user-supplied output buffer using Highway SIMD (clamp + right-shift to target precision).

Tiles whose decompression Taskflow future is still in flight (ahead of the current swath due to parallel scheduling) have their copy task chained as a Taskflow continuation, so the copy runs as soon as the tile is ready.

The output buffer (grk_swath_buffer) uses BSQ layout (one plane per component). Call grk_decompress_wait_swath_copy() to wait for all scheduled copies before accessing buf->data.

Parameters

codec	codec grk_object
swath	swath descriptor with tile_x0/y0/x1/y1 populated by grk_decompress_wait
buf	user-managed output buffer; must stay valid until grk_decompress_wait_swath_copy() returns

References grk::Codec::getImpl().

◆ grk_decompress_set_band_callback()

void grk_decompress_set_band_callback	(	grk_object *	codec,
		grk_io_band_callback	callback,
		void *	user_data )

Set a band-completion callback on the decompressor.

Must be called after grk_decompress_read_header() but before grk_decompress(). When set, the decompressor invokes the callback as each tile row completes, enabling incremental writing of decompressed image bands.

Parameters

codec	decompressor object
callback	function to invoke per completed band
user_data	opaque pointer forwarded to the callback

References grk::Codec::getImpl().

◆ grk_decompress_set_progression_state()

GRK_API bool GRK_CALLCONV grk_decompress_set_progression_state	(	grk_object *	codec,
		grk_progression_state	state )

Applies a new progression state to one or all cached tiles.

When state.single_tile is true, only the tile at state.tile_index is updated. The maximum number of quality layers to decode for each resolution level is taken from state.layers_per_resolution. If the new limit differs from the current one, the tile is marked dirty so that a subsequent grk_decompress() call re-decodes it with the new layer budget.

Typical use: decode a full swath quickly with 1 layer, then apply more layers on demand for specific tiles.

Parameters

codec	decompression codec (see grk_object)
state	desired progression state (see grk_progression_state); state.single_tile must be true (multi-tile update not supported)

Returns: true if the tile was found in the cache and the state was stored; false if single_tile is false, the tile is not cached, or the codec has no decompressor

References grk::Codec::getImpl(), GRK_API, and GRK_CALLCONV.

◆ grk_decompress_tile()

bool grk_decompress_tile	(	grk_object *	codec,
		uint16_t	tile_index )

Decompresses a single tile by index.

Decodes only the tile at tile_index without decompressing the entire image. Useful for random-access workflows where only a subset of tiles is needed. The tile index is row-major: tile_y * num_tile_cols + tile_x.

After this returns, retrieve the decoded image via grk_decompress_get_tile_image(codec, tile_index, false).

Parameters

codec	decompression codec (see grk_object)
tile_index	zero-based tile index (row-major within the tile grid)

Returns: true if the tile was decoded successfully, false on error

References grk::Codec::getImpl().

◆ grk_decompress_update()

bool grk_decompress_update	(	grk_decompress_parameters *	params,
		grk_object *	codec )

Updates decompression parameters on an already-initialized codec.

Allows changing parameters (e.g. decoding region, reduce factor, quality layers) after grk_decompress_init() but before the first grk_decompress() call. Not all parameters can be changed mid-stream; refer to grk_decompress_parameters for which fields are live-updatable.

Parameters

params	updated decompression parameters (see grk_decompress_parameters)
codec	decompression codec to update (see grk_object)

Returns: true if parameters were applied successfully, false otherwise

References grk::Codec::getImpl().

◆ grk_decompress_wait()

void grk_decompress_wait	(	grk_object *	codec,
		grk_wait_swath *	swath )

Waits for an asynchronous decompression to complete.

If swath is non-null: waits for all tiles covering the swath region, then populates swath->tile_x0/y0/x1/y1 and swath->num_tile_cols with the tile grid indices. Use these with grk_decompress_get_tile_image() to retrieve per-tile data.

If swath is null: waits for the entire decompression to complete (all tiles, all post-processing). No tile coordinates are output.

Parameters

codec	codec grk_object
swath	grk_wait_swath to wait for, or NULL for full wait

References grk::Codec::getImpl().

◆ grk_decompress_wait_swath_copy()

void grk_decompress_wait_swath_copy ( grk_object * codec )

Wait for all in-flight swath copy tasks to complete.

Blocks until every copy task submitted by grk_decompress_schedule_swath_copy() has finished. After this returns, buf->data is fully populated and safe to access.

Parameters

codec codec grk_object

References grk::Codec::getImpl().

◆ grk_deinitialize()

void grk_deinitialize ( void )

Deinitialize the Grok library.

Cleans up the plugin and thread pool. Call at the end of main() to ensure GPU resources are freed before CUDA runtime unloads.

References TFSingleton::destroy(), and grk_plugin_cleanup().

◆ grk_detect_format()

bool grk_detect_format	(	const char *	file_path,
		GRK_CODEC_FORMAT *	format )

Detect the JPEG 2000 codec format of a file by reading its magic bytes.

Reads the first bytes of the file and returns the detected format:

GRK_CODEC_JP2 for JP2 or JPH container files
GRK_CODEC_J2K for raw codestream files (J2K, J2C, JPC)
GRK_CODEC_MJ2 for Motion JPEG 2000 files

Parameters

file_path	path to the file to inspect
format	[out] detected codec format

Returns: true if a valid JPEG 2000 format was detected, false otherwise

References grk::detectFormat(), GRK_CODEC_UNK, and GRK_JPEG_2000_NUM_IDENTIFIER_BYTES.

◆ grk_dump_codec()

void grk_dump_codec	(	grk_object *	codec,
		uint32_t	info_flag,
		FILE *	output_stream )

Dumps codec diagnostic information to a stream.

Writes human-readable codec state (image dimensions, tile grid, progression order, codestream indices, etc.) to output_stream. Useful for debugging and conformance testing.

The info_flag controls which sections are emitted; combine the GRK_IMG_INFO, GRK_MH_INFO, GRK_TH_INFO, GRK_TCH_INFO, GRK_MH_IND, and GRK_TH_IND flags as needed.

Parameters

codec	codec (decompression or compression — see grk_object)
info_flag	bitmask of GRK__INFO / GRK__IND flags
output_stream	destination FILE* (e.g. stdout, stderr, or a log file)

References grk::Codec::getImpl().

◆ grk_get_data_type()

grk_data_type grk_get_data_type	(	bool	compress,
		uint8_t	prec,
		bool	is_mct,
		uint8_t	qmfbid,
		bool	fast_mct )

Determine the data type used by Grok for image component data.

Returns the data type (GRK_INT_32 or GRK_INT_16) that Grok will use for storing image component data during compression or decompression, assuming standard conditions (whole-tile decoding, num_resolutions > 1).

Parameters

compress	true for compression, false for decompression
prec	image component precision in bits
is_mct	true if multi-component transform (MCT/RCT/ICT) is applied
qmfbid	wavelet transform: 1 for reversible (5/3), 0 for irreversible (9/7)

Returns: GRK_INT_16 if the 16-bit path will be used, GRK_INT_32 otherwise

References GRK_INT_16, and GRK_INT_32.

Referenced by grk::TileProcessor::createDecompressTileComponentWindows(), and grk::TileProcessorCompress::preCompressTile().

◆ grk_image_is_post_process_no_op()

bool grk_image_is_post_process_no_op ( grk_image * image )

Checks whether the image requires post-processing (palette, ICC, colour space conversion, precision override, or upsampling).

Parameters

image pointer to the decompressed image

Returns: true if all post-processing steps are no-ops

◆ grk_image_meta_get_field()

bool grk_image_meta_get_field	(	grk_image_meta *	meta,
		const char *	field,
		uint8_t **	data,
		size_t *	len )

Get a metadata buffer from a grk_image_meta object.

Returns a pointer to the internal buffer for the specified metadata field. The pointer is valid for the lifetime of the grk_image_meta object.

Parameters

	meta	pointer to an existing grk_image_meta
	field	which metadata field to get: "geotiff", "ipr", "xmp", "iptc", "exif", "xml"
[out]	data	set to internal buffer pointer (do not free)
[out]	len	set to buffer length

Returns: true on success (even if data is NULL/empty), false on invalid field

References resolve_meta_field().

◆ grk_image_meta_new()

grk_image_meta * grk_image_meta_new ( void )

Allocates an empty image metadata object.

Returns a heap-allocated grk_image_meta that holds optional metadata (ICC profile, XMP, IPTC, EXIF) to associate with an image before compression. Free with grk_object_unref() when done.

Returns: pointer to newly allocated grk_image_meta, or NULL on OOM

Referenced by grk::CodeStreamDecompress::CodeStreamDecompress(), and grk::FileFormatJP2Compress::init().

◆ grk_image_meta_set_asocs()

bool grk_image_meta_set_asocs	(	grk_image_meta *	meta,
		const grk_asoc *	asocs,
		uint32_t	num_asocs )

Set association boxes on a grk_image_meta object for writing.

The asoc array uses a flattened tree representation:

Level 0 entries are top-level association boxes
Level N entries are children of the most recent level N-1 entry Each entry has a label and optionally XML content.

This is used for GMLJP2 metadata. The data is copied internally.

Parameters

meta	pointer to an existing grk_image_meta
asocs	array of association box entries
num_asocs	number of entries in the array

Returns: true on success, false on OOM or invalid input

References _grk_image_meta::asoc_boxes, _grk_asoc::label, _grk_asoc::level, _grk_image_meta::num_asoc_boxes, _grk_asoc::xml, and _grk_asoc::xml_len.

◆ grk_image_meta_set_field()

bool grk_image_meta_set_field	(	grk_image_meta *	meta,
		const char *	field,
		const uint8_t *	data,
		size_t	len )

Set a metadata buffer on a grk_image_meta object.

Copies len bytes from data into the specified metadata field, replacing any existing data. The previous buffer (if any) is freed.

Parameters

meta	pointer to an existing grk_image_meta
field	which metadata field to set: "geotiff", "ipr", "xmp", "iptc", "exif", "xml"
data	pointer to source bytes (copied internally)
len	number of bytes to copy

Returns: true on success, false on invalid field name or OOM

References resolve_meta_field().

◆ grk_image_new()

grk_image * grk_image_new	(	uint16_t	numcmpts,
		grk_image_comp *	cmptparms,
		GRK_COLOR_SPACE	clrspc,
		bool	alloc_data )

Allocates a new Grok image with the specified component layout.

Creates an image whose component geometry is described by cmptparms. Each entry in cmptparms specifies width, height, bit-depth, signedness, and sub-sampling factors for one component.

When alloc_data is true, a contiguous int32_t data block is allocated for every component; when false, the component data pointers are NULL and the caller must supply them before passing the image to grk_compress_init().

The returned image is reference-counted. Release with grk_object_unref().

Parameters

numcmpts	number of components (e.g. 1 for grayscale, 3 for RGB)
cmptparms	per-component parameters array — length must be `numcmpts` (see grk_image_comp)
clrspc	image colour space (e.g. GRK_CLRSPC_SRGB, GRK_CLRSPC_GRAY — see GRK_COLOR_SPACE)
alloc_data	if true, allocate int32_t data buffers for all components

Returns: pointer to newly allocated grk_image, or NULL on failure

References grk::GrkImage::create().

◆ grk_initialize()

void grk_initialize	(	const char *	plugin_path,
		uint32_t	num_threads,
		bool *	plugin_initialized )

Initializes the Grok library.

Must be called once before any other Grok API function. It is safe to call multiple times; subsequent calls are no-ops unless the library was shut down.

Sets up the Taskflow thread pool used by all async decompress/compress operations. Pass num_threads = 0 to use all available logical CPUs. The thread pool persists for the lifetime of the process.

Parameters

plugin_path	path to an optional hardware-accelerator plugin .so; pass NULL for CPU-only operation
num_threads	number of worker threads (0 = use all CPUs)
plugin_initialized	if non-NULL, set to true when a plugin was loaded and initialized successfully, false otherwise

References TFSingleton::create(), debugCallback(), errorCallback(), grk_plugin_load(), grk_set_msg_handlers(), grk::grklog, infoCallback(), initMutex, initState_, grk::Logger::logger_, traceCallback(), and warningCallback().

Referenced by grk_compress(), grk_decompress(), and grk_transcode().

◆ grk_num_workers()

size_t grk_num_workers ( void )

Returns the number of worker threads in the core thread pool.

Returns: total number of threads (including the driver thread)

References TFSingleton::num_threads().

Referenced by grk::num_workers().

◆ grk_object_ref()

GRK_API grk_object *GRK_CALLCONV grk_object_ref ( grk_object * obj )

Increments the reference count on a Grok object.

Call this when you want to share ownership of a codec or image object across multiple owners. Each call to grk_object_ref() must be matched by exactly one call to grk_object_unref().

Parameters

obj	Grok object (see grk_object); passing NULL is a no-op

Returns: the same obj pointer (for convenience), or NULL if obj is NULL

References GRK_API, and GRK_CALLCONV.

Referenced by grk::grk_ref().

◆ grk_object_unref()

GRK_API void GRK_CALLCONV grk_object_unref ( grk_object * obj )

Decrements the reference count on a Grok object.

When the reference count reaches zero the object (codec or image) is destroyed and all associated decompressor/compressor resources are freed. The caller must not access the object after this call if its count reaches zero.

For a decompressor codec: completes any in-flight async tasks before destroying the object. For an image: frees component data buffers.

Parameters

obj	Grok object (see grk_object); passing NULL is a no-op

References GRK_API, and GRK_CALLCONV.

Referenced by grk_compress_init(), grk_decompress_init(), grk_transcode(), grk::grk_unref(), and grk::FileFormatJP2Compress::transcodeCodestream().

◆ grk_plugin_batch_compress()

int32_t grk_plugin_batch_compress ( grk_plugin_compress_batch_info info )

Compresses a directory of images in batch using the hardware plugin.

Scans info.input_dir for supported source images, compresses each one with plugin acceleration, and writes results to info.output_dir. A per-image info.callback is invoked for each file to allow custom output naming and post-processing.

Parameters

info	batch job description: input/output directories, compression parameters, and per-file callback (see grk_plugin_compress_batch_info)

Returns: 0 if all files were queued successfully, non-zero on error

References _gpup_compress_batch_info::callback, _gpup_compress_batch_info::compress_parameters, grk_plugin_internal_encode_callback(), grk::grk_to_gpup_compress_params(), _gpup_compress_batch_info::input_dir, grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), _gpup_compress_batch_info::output_dir, plugin_batch_encode_method_name, pluginLoaded, s_originalCompressParams, and userEncodeCallback.

◆ grk_plugin_batch_decompress()

int32_t grk_plugin_batch_decompress ( void )

Starts (resumes) the queued batch decompress operation.

Begins processing files registered by grk_plugin_init_batch_decompress(). Returns immediately; use grk_plugin_wait_for_batch_complete() (or poll via callbacks) to track completion.

Returns: 0 on success, non-zero if the batch was not initialised or a fatal scheduling error occurred

References grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_batch_decode_method_name, and pluginLoaded.

◆ grk_plugin_cleanup()

void grk_plugin_cleanup ( void )

Unloads the plugin and releases all plugin-owned resources.

Signals the plugin to drain any in-flight GPU/FPGA work, then closes the shared library handle. Call before process exit or before loading a different plugin version.

Safe to call even if no plugin is loaded (no-op in that case).

References grk::minpf_cleanup_plugin_manager(), and pluginLoaded.

Referenced by grk_deinitialize(), and GrkCleanup::~GrkCleanup().

◆ grk_plugin_compress()

int32_t grk_plugin_compress	(	grk_cparameters *	compress_parameters,
		GRK_PLUGIN_COMPRESS_USER_CALLBACK	callback )

Compresses a single image using the loaded hardware plugin.

Uses the plugin-accelerated T1 encoder. For CPU-only encoding use grk_compress() instead. The callback is invoked on completion with the compressed byte count and any error code.

Parameters

compress_parameters	compression settings (see grk_cparameters)
callback	completion callback (see GRK_PLUGIN_COMPRESS_USER_CALLBACK)

Returns: 0 on success, non-zero error code on failure

References grk_plugin_internal_encode_callback(), grk::grk_to_gpup_compress_params(), grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_encode_method_name, pluginLoaded, s_originalCompressParams, and userEncodeCallback.

◆ grk_plugin_decompress()

int32_t grk_plugin_decompress	(	grk_decompress_parameters *	decompress_parameters,
		grk_plugin_decompress_callback	callback )

Decompresses a single JPEG 2000 image using the loaded hardware plugin.

Uses plugin-accelerated T1 entropy decoding. For CPU-only decoding use grk_decompress() instead. The callback is invoked on completion.

Parameters

decompress_parameters	decompression settings (see grk_decompress_parameters)
callback	per-image completion callback (see grk_plugin_decompress_callback)

Returns: 0 on success, non-zero error code on failure

References decodeCallback, grk_plugin_internal_decode_callback(), grk::grk_to_gpup_decompress_params(), grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_decode_method_name, pluginLoaded, and s_originalDecompressParams.

◆ grk_plugin_get_debug_state()

uint32_t grk_plugin_get_debug_state ( )

Returns the current debug state bitmask of the loaded plugin.

The returned value is a combination of GRK_PLUGIN_STATE_* flags:

GRK_PLUGIN_STATE_NO_DEBUG (0x0) — production mode, no debug output
GRK_PLUGIN_STATE_DEBUG (0x1) — T1 debug comparisons enabled
GRK_PLUGIN_STATE_PRE_TR1 (0x2) — pre-T1 DWT/MCT data compared
GRK_PLUGIN_STATE_DWT_QUANTIZATION (0x4) — DWT quantisation compared
GRK_PLUGIN_STATE_MCT_ONLY (0x8) — only MCT stage compared

Returns 0 (GRK_PLUGIN_STATE_NO_DEBUG) if no plugin is loaded.

Returns: bitmask of active GRK_PLUGIN_STATE_* flags

References GRK_PLUGIN_STATE_NO_DEBUG, grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_get_debug_state_method_name, and pluginLoaded.

Referenced by grk::compress_synch_with_plugin(), grk::TileProcessorCompress::doCompress(), grk::TileProcessor::init(), grk::TileProcessorCompress::pcrdBisectFeasible(), grk::TileProcessorCompress::pcrdBisectSimple(), grk::TileProcessorCompress::syncPluginCodeBlockData(), and grk::tile_equals().

◆ grk_plugin_init()

GRK_API bool GRK_CALLCONV grk_plugin_init ( grk_plugin_init_info init_info )

Initializes a loaded plugin with a device and license.

Must be called after grk_plugin_load() and before any compress or decompress operation that uses the plugin. Connects the plugin to the specified accelerator device and validates the license string.

Parameters

init_info device ID, license key, and optional server address (see grk_plugin_init_info)

Returns: true if the plugin accepted the device and license, false on invalid license, device unavailable, or no plugin loaded

References _grk_plugin_init_info::device_id, _gpup_init_info::deviceId, GRK_API, GRK_CALLCONV, _gpup_init_info::license, _grk_plugin_init_info::license, grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_init_method_name, pluginLoaded, _gpup_init_info::server, _grk_plugin_init_info::server, _gpup_init_info::verbose, and _grk_plugin_init_info::verbose.

◆ grk_plugin_init_batch_decompress()

int32_t grk_plugin_init_batch_decompress	(	const char *	input_dir,
		const char *	output_dir,
		grk_decompress_parameters *	decompress_parameters,
		grk_plugin_decompress_callback	callback )

Initialises a batch plugin decompress operation but does not start it.

Sets up a batch decompression pipeline: scans input_dir, pairs each file with decompress_parameters, and registers callback for per-file results. Call grk_plugin_batch_decompress() to start decoding.

Parameters

input_dir	directory containing JPEG 2000 source files
output_dir	directory to write decompressed output files
decompress_parameters	shared decompression settings for all files (see grk_decompress_parameters)
callback	per-image result callback (see grk_plugin_decompress_callback)

Returns: 0 on success, non-zero on error (missing directory, bad parameters)

References decodeCallback, grk_plugin_internal_decode_callback(), grk::grk_to_gpup_decompress_params(), grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_init_batch_decode_method_name, pluginLoaded, and s_originalDecompressParams.

◆ grk_plugin_internal_decode_callback()

int32_t grk_plugin_internal_decode_callback ( PluginDecodeCallbackInfo * info )

References decodeCallback, GPUP_DECODE_T2, grk::gpup_image_free_shell(), grk::gpup_tile_to_grk(), grk::gpup_tile_update_grk(), grk::gpup_to_grk_header_info(), GRK_PLUGIN_DECODE_CLEAN, grk::grk_plugin_tile_free_wrapper(), grk::grk_tile_sync_metadata_to_gpup(), grk::grk_to_gpup_header_info(), grk::grk_to_gpup_image(), grk_to_gpup_init_decompressors_bridge(), s_gpupInitDecompressorsFn, and s_originalDecompressParams.

Referenced by grk_plugin_decompress(), and grk_plugin_init_batch_decompress().

◆ grk_plugin_internal_encode_callback()

uint64_t grk_plugin_internal_encode_callback ( gpup_compress_callback_info * info )

Referenced by grk_plugin_batch_compress(), and grk_plugin_compress().

◆ grk_plugin_load()

bool grk_plugin_load ( grk_plugin_load_info info )

Loads a hardware-accelerator plugin (.so / .dll).

Should be called after grk_initialize(), before grk_compress_init() or grk_decompress_init(). The plugin extends Grok with GPU or FPGA acceleration for T1 entropy coding. If loading fails, Grok falls back to CPU-only operation transparently.

Only one plugin may be loaded at a time. Call grk_plugin_cleanup() to unload the current plugin before loading a new one.

Parameters

info	plugin path and options (see grk_plugin_load_info)

Returns: true if the plugin was loaded and its ABI version is compatible, false otherwise

References grk::minpf_cleanup_plugin_manager(), grk::minpf_get_dynamic_library_extension(), grk::minpf_load_from_path(), and pluginLoaded.

Referenced by grk_initialize().

◆ grk_plugin_stop_batch_compress()

void grk_plugin_stop_batch_compress ( void )

Requests cancellation of a running batch compress operation.

Sets a stop flag that causes the batch scheduler to skip remaining queued files. Already-in-flight jobs are allowed to complete. Call grk_plugin_wait_for_batch_complete() after this to ensure a clean shutdown.

References grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_stop_batch_encode_method_name, and pluginLoaded.

◆ grk_plugin_stop_batch_decompress()

void grk_plugin_stop_batch_decompress ( void )

Requests cancellation of a running batch decompress operation.

Sets a stop flag that causes the batch scheduler to skip remaining files. Already-in-flight jobs complete normally. After calling this, wait for grk_plugin_wait_for_batch_complete() before accessing output.

References grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_stop_batch_decode_method_name, and pluginLoaded.

◆ grk_plugin_wait_for_batch_complete()

GRK_API void GRK_CALLCONV grk_plugin_wait_for_batch_complete ( void )

Blocks until all pending plugin batch jobs have completed.

Should be called after grk_plugin_batch_compress() returns to ensure all asynchronously queued compression tasks have finished before the caller inspects output files or calls grk_plugin_cleanup().

References funcPluginWaitForBatchComplete, GRK_API, GRK_CALLCONV, grk::minpf_get_plugin_manager(), grk::minpf_get_symbol(), plugin_wait_for_batch_complete_method_name, and pluginLoaded.

◆ grk_set_MCT()

bool grk_set_MCT	(	grk_cparameters *	parameters,
		const float *	encoding_matrix,
		const int32_t *	dc_shift,
		uint32_t	nb_comp )

Installs a custom Multi-Component Transform (MCT) matrix.

Overrides the default RGB→YCbCr colour transform with a user-supplied floating-point matrix. The matrix must be square (nb_comp × nb_comp) stored in row-major order. A matching DC shift vector (one value per component) is applied after the transform.

Only meaningful for compression; ignored for decompression. Must be called before grk_compress_init().

Parameters

parameters	compression parameters to update (see grk_cparameters)
encoding_matrix	row-major nb_comp×nb_comp transform matrix
dc_shift	per-component DC shift values (array of `nb_comp` int32_t)
nb_comp	number of image components (matrix dimension)

Returns: true if the matrix was stored successfully, false on invalid input

References GRK_EXTENSION_MCT, GRK_IS_PART2, grk::grk_malloc(), and GRK_PROFILE_PART2.

◆ grk_set_msg_handlers()

GRK_API void GRK_CALLCONV grk_set_msg_handlers ( grk_msg_handlers msg_handlers )

Installs application-defined log message handlers.

Replaces the default handlers (which print to stderr/stdout) with user-supplied callbacks for info, warning, and error messages. Call before grk_initialize() or at any point to change handlers. Passing a NULL function pointer for any handler restores the default behaviour for that level.

Parameters

msg_handlers struct of {info, warn, error} function pointers (see grk_msg_handlers)

References GRK_API, GRK_CALLCONV, and grk::Logger::logger_.

Referenced by grk_initialize().

◆ grk_thread_pool()

void * grk_thread_pool ( void )

Returns an opaque handle to the core thread-pool executor.

The handle is a pointer to the internal tf::Executor. Cast it back with the helpers in grk_thread_pool.h (C++ only) or use grk_num_workers() / grk_worker_id() from C.

Returns: opaque executor handle, or NULL if the library is not initialised

References TFSingleton::get().

Referenced by grk::executor().

◆ grk_to_gpup_init_decompressors_bridge()

int grk_to_gpup_init_decompressors_bridge	(	grk_header_info *	hdr,
		grk_image *	img )

static

References grk::gpup_image_free_shell(), grk::gpup_to_grk_header_info(), grk::grk_to_gpup_header_info(), grk::grk_to_gpup_image(), and s_gpupInitDecompressorsFn.

Referenced by grk_plugin_internal_decode_callback().

◆ grk_transcode()

uint64_t grk_transcode	(	grk_stream_params *	src_stream,
		grk_stream_params *	dst_stream,
		grk_cparameters *	parameters,
		grk_image *	image )

Transcodes a JPEG 2000 file by rewriting JP2 boxes while copying the codestream verbatim.

Opens the source stream, parses box headers to locate the contiguous codestream (JP2C) box, then writes a new JP2 file to dst_stream using the metadata from image and the box-level settings in parameters (branding, resolution, geoboxes placement, etc.). The raw J2K codestream is copied byte-for-byte from source to destination without re-encoding.

The image must carry the desired output metadata in its grk_image_meta (XMP, IPTC, EXIF, GeoTIFF, IPR, XML, association boxes, channel definitions, colour space, ICC profile, etc.). Populate these fields before calling this function — typically by decompressing the source header with grk_decompress_read_header(), then modifying the metadata as needed.

Parameters

src_stream	source stream description (must be readable, see grk_stream_params)
dst_stream	destination stream description (must be writable, see grk_stream_params)
parameters	compression / transcode settings (see grk_cparameters); box-level fields (jpx_branding, write_rreq, geoboxes_after_jp2c, resolution, etc.) are honoured
image	source image carrying component info and metadata (see grk_image)