Read, transform, and write UltraHDR JPEG images. More...

Collaboration diagram for UltraHDR:

Data Structures
struct	gdUhdrError
	Structured error details for UltraHDR APIs. More...

UltraHDR Types
enum	gdUhdrFormat { GD_UHDR_FORMAT_JPEG = 0 , GD_UHDR_FORMAT_WEBP = 1 , GD_UHDR_FORMAT_HEIF = 2 }
	UltraHDR container format selector. More...

typedef struct gdUhdrImageStruct	gdUhdrImage
	Opaque UltraHDR image handle.

typedef gdUhdrImage *	gdUhdrImagePtr
	Pointer to an opaque UltraHDR image handle.

typedef gdUhdrError *	gdUhdrErrorPtr
	Pointer to a gdUhdrError structure.

UltraHDR Reading
gdUhdrImagePtr	gdUhdrImageCreateFromFile (const char *filename, int format, gdUhdrErrorPtr err)
	Create an UltraHDR image handle from a file path.

gdUhdrImagePtr	gdUhdrImageCreateFromCtx (gdIOCtxPtr ctx, int format, gdUhdrErrorPtr err)
	Create an UltraHDR image handle from an IO context.

gdUhdrImagePtr	gdUhdrImageCreateFromPtr (int size, void *data, int format, gdUhdrErrorPtr err)
	Create an UltraHDR image handle from memory.

void	gdUhdrImageDestroy (gdUhdrImagePtr im)
	Destroy an UltraHDR image handle.

UltraHDR Availability and Inspection
int	gdUhdrIsAvailable (void)
	Return whether UltraHDR support is available in this build.

int	gdUhdrImageWidth (gdUhdrImagePtr im)
	Return the UltraHDR image width.

int	gdUhdrImageHeight (gdUhdrImagePtr im)
	Return the UltraHDR image height.

int	gdUhdrImageHasGainMap (gdUhdrImagePtr im)
	Return whether the UltraHDR image has a gain map.

UltraHDR Transform Queue
int	gdUhdrImageResize (gdUhdrImagePtr im, int width, int height, gdUhdrErrorPtr err)
	Queue an UltraHDR-preserving resize operation.

int	gdUhdrImageCrop (gdUhdrImagePtr im, int left, int top, int width, int height, gdUhdrErrorPtr err)
	Queue an UltraHDR-preserving crop operation.

int	gdUhdrImageRotate (gdUhdrImagePtr im, int degrees, gdUhdrErrorPtr err)
	Queue an UltraHDR-preserving right-angle rotation.

int	gdUhdrImageMirror (gdUhdrImagePtr im, int axis, gdUhdrErrorPtr err)
	Queue an UltraHDR-preserving mirror operation.

UltraHDR Writing
int	gdUhdrImageFile (gdUhdrImagePtr im, const char *filename, int format, int quality, gdUhdrErrorPtr err)
	Write an UltraHDR image to a file path.

int	gdUhdrImageCtx (gdUhdrImagePtr im, gdIOCtxPtr ctx, int format, int quality, gdUhdrErrorPtr err)
	Write an UltraHDR image to an IO context.

void *	gdUhdrImageWritePtr (gdUhdrImagePtr im, int *size, int format, int quality, gdUhdrErrorPtr err)
	Write an UltraHDR image to a newly allocated memory buffer.

UltraHDR SDR Extraction
gdImagePtr	gdUhdrImageGetSdr (gdUhdrImagePtr im, gdUhdrErrorPtr err)
	Decode the SDR view of an UltraHDR image as a gdImage.

UltraHDR Status Codes
#define	GD_UHDR_SUCCESS 0

#define	GD_UHDR_NOT_AVAILABLE -1

#define	GD_UHDR_E_INVALID -2

#define	GD_UHDR_E_UNSUPPORTED -3

#define	GD_UHDR_E_ENCODE -4

#define	GD_UHDR_E_DECODE -5

UltraHDR Transform Constants
#define	GD_UHDR_MIRROR_HORIZONTAL 0

#define	GD_UHDR_MIRROR_VERTICAL 1

Detailed Description

Read, transform, and write UltraHDR JPEG images.

UltraHDR stores an SDR base image plus a gain map that allows HDR reconstruction. gd's normal gdImage representation cannot safely represent that gain map because it is not an ordinary 8-bit or palette bitmap; it may be a floating-point-style image with metadata that must stay aligned with the SDR base image. For that reason, UltraHDR support uses a separate opaque gdUhdrImage handle and performs UltraHDR-aware operations through libultrahdr.

Do not convert a gdUhdrImagePtr to gdImagePtr and expect to write it back as UltraHDR. gdUhdrImageGetSdr() intentionally returns only a standard SDR gdImagePtr view. That image can be inspected or saved as ordinary JPEG/PNG, but it no longer carries the gain map needed to recreate a valid UltraHDR image. Future GD versions may add internal image formats that can represent the gain map directly; until then, use gdUhdrImageResize(), gdUhdrImageCrop(), gdUhdrImageRotate(), and gdUhdrImageMirror() to queue supported UltraHDR-preserving transformations.

gdUhdrImagePtr im;
gdImagePtr sdr;
gdUhdrError err;
int rc;
 
im = gdUhdrImageCreateFromFile("input.jpg", GD_UHDR_FORMAT_JPEG, &err);
if (im == NULL) {
    return 1;
}
 
rc = gdUhdrImageResize(im, 640, 360, &err);
if (rc != GD_UHDR_SUCCESS) {
    gdUhdrImageDestroy(im);
    return 1;
}
 
rc = gdUhdrImageFile(im, "output.jpg", GD_UHDR_FORMAT_JPEG, 90, &err);
if (rc != GD_UHDR_SUCCESS) {
    gdUhdrImageDestroy(im);
    return 1;
}
 
sdr = gdUhdrImageGetSdr(im, &err);
if (sdr != NULL) {
    gdImageDestroy(sdr);
}
 
gdUhdrImageDestroy(im);

Macro Definition Documentation

◆ GD_UHDR_E_DECODE

#define GD_UHDR_E_DECODE -5

Decode failure.

◆ GD_UHDR_E_ENCODE

#define GD_UHDR_E_ENCODE -4

Encode failure.

◆ GD_UHDR_E_INVALID

#define GD_UHDR_E_INVALID -2

Invalid argument or state.

◆ GD_UHDR_E_UNSUPPORTED

#define GD_UHDR_E_UNSUPPORTED -3

Unsupported format or operation.

◆ GD_UHDR_MIRROR_HORIZONTAL

#define GD_UHDR_MIRROR_HORIZONTAL 0

Mirror an UltraHDR image horizontally.

◆ GD_UHDR_MIRROR_VERTICAL

#define GD_UHDR_MIRROR_VERTICAL 1

Mirror an UltraHDR image vertically.

◆ GD_UHDR_NOT_AVAILABLE

#define GD_UHDR_NOT_AVAILABLE -1

libgd was built without UltraHDR support.

◆ GD_UHDR_SUCCESS

#define GD_UHDR_SUCCESS 0

Operation succeeded.

Enumeration Type Documentation

◆ gdUhdrFormat

enum gdUhdrFormat

UltraHDR container format selector.

Enumerator
GD_UHDR_FORMAT_JPEG	UltraHDR JPEG, currently supported.
GD_UHDR_FORMAT_WEBP	Reserved for future WebP-based UltraHDR support.
GD_UHDR_FORMAT_HEIF	Reserved for future HEIF-based UltraHDR support.

Function Documentation

◆ gdUhdrImageCreateFromCtx()

gdUhdrImagePtr gdUhdrImageCreateFromCtx	(	gdIOCtxPtr	ctx,
		int	format,
		gdUhdrErrorPtr	err
	)

Create an UltraHDR image handle from an IO context.

gdUhdrImageCreateFromCtx() reads all data from ctx but does not close it. Currently only GD_UHDR_FORMAT_JPEG is supported. The returned handle is owned by the caller and must be destroyed with gdUhdrImageDestroy(). If err is not NULL, it receives status details.

Parameters

ctx	Input IO context.
format	Input format, currently GD_UHDR_FORMAT_JPEG.
err	Optional pointer to receive detailed error information.

Returns: A new UltraHDR image handle, or NULL on error.

◆ gdUhdrImageCreateFromFile()

gdUhdrImagePtr gdUhdrImageCreateFromFile	(	const char *	filename,
		int	format,
		gdUhdrErrorPtr	err
	)

Create an UltraHDR image handle from a file path.

gdUhdrImageCreateFromFile() reads filename and validates that it is an UltraHDR image in the selected format. Currently only GD_UHDR_FORMAT_JPEG is supported. The returned handle is owned by the caller and must be destroyed with gdUhdrImageDestroy(). If err is not NULL, it receives status details.

Parameters

filename	Path to the UltraHDR input file.
format	Input format, currently GD_UHDR_FORMAT_JPEG.
err	Optional pointer to receive detailed error information.

Returns: A new UltraHDR image handle, or NULL on error.

◆ gdUhdrImageCreateFromPtr()

gdUhdrImagePtr gdUhdrImageCreateFromPtr	(	int	size,
		void *	data,
		int	format,
		gdUhdrErrorPtr	err
	)

Create an UltraHDR image handle from memory.

gdUhdrImageCreateFromPtr() reads size bytes from data without taking ownership of the buffer. Currently only GD_UHDR_FORMAT_JPEG is supported. The returned handle is owned by the caller and must be destroyed with gdUhdrImageDestroy(). If err is not NULL, it receives status details.

Parameters

size	Size of data in bytes.
data	Pointer to UltraHDR data.
format	Input format, currently GD_UHDR_FORMAT_JPEG.
err	Optional pointer to receive detailed error information.

Returns: A new UltraHDR image handle, or NULL on error.

◆ gdUhdrImageCrop()

int gdUhdrImageCrop	(	gdUhdrImagePtr	im,
		int	left,
		int	top,
		int	width,
		int	height,
		gdUhdrErrorPtr	err
	)

Queue an UltraHDR-preserving crop operation.

The operation is recorded on im and applied when the image is written. The SDR base image and gain map are cropped together so the output can remain a valid UltraHDR image.

Parameters

im	UltraHDR image handle.
left	Left edge of the crop rectangle in pixels.
top	Top edge of the crop rectangle in pixels.
width	Crop width in pixels.
height	Crop height in pixels.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageCtx()

int gdUhdrImageCtx	(	gdUhdrImagePtr	im,
		gdIOCtxPtr	ctx,
		int	format,
		int	quality,
		gdUhdrErrorPtr	err
	)

Write an UltraHDR image to an IO context.

gdUhdrImageCtx() does not close ctx. Currently only GD_UHDR_FORMAT_JPEG is supported. If no transform operations were queued, gd writes the original compressed UltraHDR data through. If transforms were queued, gd uses libultrahdr to produce a new UltraHDR JPEG with the gain map preserved.

Parameters

im	UltraHDR image handle to write.
ctx	Output IO context.
format	Output format, currently GD_UHDR_FORMAT_JPEG.
quality	JPEG quality from 1 to 95.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageDestroy()

void gdUhdrImageDestroy ( gdUhdrImagePtr im )

Destroy an UltraHDR image handle.

Use this for handles returned by gdUhdrImageCreateFromFile(), gdUhdrImageCreateFromCtx(), or gdUhdrImageCreateFromPtr(). Passing NULL is allowed.

Parameters

im	UltraHDR image handle to destroy.

◆ gdUhdrImageFile()

int gdUhdrImageFile	(	gdUhdrImagePtr	im,
		const char *	filename,
		int	format,
		int	quality,
		gdUhdrErrorPtr	err
	)

Write an UltraHDR image to a file path.

Currently only GD_UHDR_FORMAT_JPEG is supported. If no transform operations were queued, gd writes the original compressed UltraHDR data through. If transforms were queued, gd uses libultrahdr to decode the base image and gain map, applies the queued operations to both, and re-encodes an UltraHDR JPEG.

Parameters

im	UltraHDR image handle to write.
filename	Output file path.
format	Output format, currently GD_UHDR_FORMAT_JPEG.
quality	JPEG quality from 1 to 95.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageGetSdr()

gdImagePtr gdUhdrImageGetSdr	(	gdUhdrImagePtr	im,
		gdUhdrErrorPtr	err
	)

Decode the SDR view of an UltraHDR image as a gdImage.

The returned gdImagePtr is caller-owned and must be destroyed with gdImageDestroy. It is an SDR image only: it does not contain the UltraHDR gain map and cannot be used to recreate an UltraHDR image. Use the gdUhdrImage* transform and write APIs when the gain map must be preserved.

Parameters

im	UltraHDR image handle to decode.
err	Optional pointer to receive detailed error information.

Returns: A newly allocated truecolor SDR image, or NULL on error.

◆ gdUhdrImageHasGainMap()

int gdUhdrImageHasGainMap ( gdUhdrImagePtr im )

Return whether the UltraHDR image has a gain map.

Parameters

im	UltraHDR image handle.

Returns: 1 if im has a gain map, or 0 otherwise.

◆ gdUhdrImageHeight()

int gdUhdrImageHeight ( gdUhdrImagePtr im )

Return the UltraHDR image height.

Parameters

im	UltraHDR image handle.

Returns: Image height in pixels, or 0 for NULL.

◆ gdUhdrImageMirror()

int gdUhdrImageMirror	(	gdUhdrImagePtr	im,
		int	axis,
		gdUhdrErrorPtr	err
	)

Queue an UltraHDR-preserving mirror operation.

The operation is recorded on im and applied when the image is written. The SDR base image and gain map are mirrored together so the output can remain a valid UltraHDR image.

Parameters

im	UltraHDR image handle.
axis	Mirror axis, GD_UHDR_MIRROR_HORIZONTAL or GD_UHDR_MIRROR_VERTICAL.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageResize()

int gdUhdrImageResize	(	gdUhdrImagePtr	im,
		int	width,
		int	height,
		gdUhdrErrorPtr	err
	)

Queue an UltraHDR-preserving resize operation.

The operation is recorded on im and applied when the image is written. The SDR base image and gain map are transformed together so the output can remain a valid UltraHDR image.

Parameters

im	UltraHDR image handle.
width	Output width in pixels.
height	Output height in pixels.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageRotate()

int gdUhdrImageRotate	(	gdUhdrImagePtr	im,
		int	degrees,
		gdUhdrErrorPtr	err
	)

Queue an UltraHDR-preserving right-angle rotation.

The operation is recorded on im and applied when the image is written. The SDR base image and gain map are rotated together so the output can remain a valid UltraHDR image. Supported angles are 0, 90, 180, and 270 degrees.

Parameters

im	UltraHDR image handle.
degrees	Rotation angle in degrees.
err	Optional pointer to receive detailed error information.

Returns: GD_UHDR_SUCCESS on success, or another GD_UHDR_* status code on error.

◆ gdUhdrImageWidth()

int gdUhdrImageWidth ( gdUhdrImagePtr im )

Return the UltraHDR image width.

Parameters

im	UltraHDR image handle.

Returns: Image width in pixels, or 0 for NULL.

◆ gdUhdrImageWritePtr()

void * gdUhdrImageWritePtr	(	gdUhdrImagePtr	im,
		int *	size,
		int	format,
		int	quality,
		gdUhdrErrorPtr	err
	)

Write an UltraHDR image to a newly allocated memory buffer.

Currently only GD_UHDR_FORMAT_JPEG is supported. On success, the returned buffer is owned by the caller and must be freed with gdFree().

Parameters

im	UltraHDR image handle to write.
size	Pointer that receives the encoded buffer size in bytes.
format	Output format, currently GD_UHDR_FORMAT_JPEG.
quality	JPEG quality from 1 to 95.
err	Optional pointer to receive detailed error information.

Returns: A newly allocated UltraHDR data buffer, or NULL on error.

◆ gdUhdrIsAvailable()

int gdUhdrIsAvailable ( void )

Return whether UltraHDR support is available in this build.

This reports whether libgd was built with libultrahdr support.

Returns: 1 when UltraHDR support is available, or 0 otherwise.

Data Structures

UltraHDR Types

UltraHDR Reading

UltraHDR Availability and Inspection

UltraHDR Transform Queue

UltraHDR Writing

UltraHDR SDR Extraction

UltraHDR Status Codes

UltraHDR Transform Constants

Detailed Description

Macro Definition Documentation

◆ GD_UHDR_E_DECODE

◆ GD_UHDR_E_ENCODE

◆ GD_UHDR_E_INVALID

◆ GD_UHDR_E_UNSUPPORTED

◆ GD_UHDR_MIRROR_HORIZONTAL

◆ GD_UHDR_MIRROR_VERTICAL

◆ GD_UHDR_NOT_AVAILABLE

◆ GD_UHDR_SUCCESS

Enumeration Type Documentation

◆ gdUhdrFormat

Function Documentation

◆ gdUhdrImageCreateFromCtx()

◆ gdUhdrImageCreateFromFile()

◆ gdUhdrImageCreateFromPtr()

◆ gdUhdrImageCrop()

◆ gdUhdrImageCtx()

◆ gdUhdrImageDestroy()

◆ gdUhdrImageFile()

◆ gdUhdrImageGetSdr()

◆ gdUhdrImageHasGainMap()

◆ gdUhdrImageHeight()

◆ gdUhdrImageMirror()

◆ gdUhdrImageResize()

◆ gdUhdrImageRotate()

◆ gdUhdrImageWidth()

◆ gdUhdrImageWritePtr()

◆ gdUhdrIsAvailable()