Skip to content

Context

The ph_context_t that holds one image and its configuration: create, free, and what is loaded.

Types
ph_context_t Opaque context structure holding image data and configuration. Treat this as a void* in FFI.
Functions
ph_create() Allocates a new context with default settings (Gamma 1.0, identity).
ph_free() Frees the context and all associated image memory.
ph_context_get_dimensions() Returns the dimensions of the currently loaded image.
ph_is_loaded() Checks if an image is currently loaded in the context.

Types

ph_context_t

typedef struct ph_context ph_context_t;

Opaque context structure holding image data and configuration. Treat this as a void* in FFI.

Note

Thread-safety contract: one context per thread at a time. Distinct threads each using their own ph_context_t may call into the library concurrently with no further synchronization – nothing here is process-global mutable state. A single ph_context_t is not safe to use from two threads at once, including two threads merely reading it concurrently (e.g. one loading a new image while another reads ph_get_last_error_message()); that pairing is the caller's to serialize, not the library's. ph_hash_files()/ph_hash_buffers() follow this same rule internally: each worker thread in their pool creates and owns its own context. They take no context themselves, so several threads may run batches at the same time. One image is always loaded and hashed on a single thread – parallelism is across images, through the batch functions or the caller's own threads. See Hashing many files.

Explained in Hashing many files · How libphash works

Functions

ph_create()

ph_error_t ph_create(ph_context_t **out_ctx);

nodiscard · returns ph_error_t

Allocates a new context with default settings (Gamma 1.0, identity).

Parameters

Parameter Direction Description
out_ctx out Pointer to the created context. Untouched on error.

Returns PH_SUCCESS, PH_ERR_INVALID_ARGUMENT for a NULL out_ctx, or PH_ERR_ALLOCATION_FAILED.

Used in basic_hash.c · batch_hash.c · cmake_consumer/main.c · compare_two_images.c · configure.c · digest_and_metrics.c · error_handling.c · hash_distance.c · load_sources.c

Explained in Handling errors · How libphash works · Quick start

ph_free()

void ph_free(ph_context_t *ctx);

Frees the context and all associated image memory.

Parameters

Parameter Description
ctx The context to free. Safe to pass NULL.

Used in basic_hash.c · batch_hash.c · cmake_consumer/main.c · compare_two_images.c · configure.c · digest_and_metrics.c · error_handling.c · hash_distance.c · load_sources.c

Explained in Handling errors · How libphash works · Quick start

ph_context_get_dimensions()

void ph_context_get_dimensions(
    const ph_context_t *ctx,
    int *width,
    int *height,
    int *channels);

Returns the dimensions of the currently loaded image.

With no image loaded – a fresh context, or one whose last ph_load_from_file() / ph_load_from_memory() failed – every output is set to 0. A failed ph_load_from_pixels() is the exception: it keeps the previous image, and so its dimensions. ph_is_loaded() tells "no image" apart from anything else.

Parameters

Parameter Description
ctx The context. With NULL, nothing is written.
width Output for width; may be NULL.
height Output for height; may be NULL.
channels Output for number of channels – 1 or 3; may be NULL. An alpha channel is resolved at load time (ph_context_set_alpha_mode()) and never stored.

Used in error_handling.c

Explained in Loading images

ph_is_loaded()

int ph_is_loaded(const ph_context_t *ctx);

returns int

Checks if an image is currently loaded in the context.

Returns 1 if loaded, 0 otherwise (including for a NULL ctx).

Used in error_handling.c

Explained in Loading images