vmafx/context.h¶
Contexts: options, feature and model registration, submit, flush, extractor introspection.
#include <vmafx/context.h>.
Handles and callbacks¶
| Type | Since | Description |
|---|---|---|
VmafxContext | 0.1 | One scoring session. Released by vmafx_context_destroy. |
Structs¶
VmafxContextConfig¶
Context configuration. Initialise with VMAFX_CONTEXT_CONFIG_INIT. Size 56 bytes, alignment 8. Since 0.1.
| Field | C declaration | Offset | Since | Description |
|---|---|---|---|---|
struct_size | uint32_t struct_size | 0 | 0.1 | Size of this struct as the caller compiled it; set by the _INIT macro. |
log_level | uint32_t log_level | 4 | 0.1 | Log verbosity. Values: VmafxLogLevel. |
n_threads | uint32_t n_threads | 8 | 0.1 | Worker threads; 0 runs extractors on the calling thread. |
n_subsample | uint32_t n_subsample | 12 | 0.1 | Score every n-th frame; 0 and 1 score every frame. |
cpumask | uint64_t cpumask | 16 | 0.1 | CPU instruction-set bits to disable. |
gpumask | uint64_t gpumask | 24 | 0.1 | GPU dispatch bits to disable. |
log_callback | VmafxLogCallback log_callback | 32 | 0.1 | Receives every message the library raises for this context at or below log_level, on the calling thread and on the context's worker threads, and every failure reported without an error out-parameter; nothing of the context then reaches the process log (ADR-1906). NULL: the process log (stderr), whose level the context then sets, as vmaf_init() does. Added in ABI 0.1.1. |
log_user | void *log_user | 40 | 0.1 | Passed to log_callback. Added in ABI 0.1.1. |
import_retry_wait_ns | uint64_t import_retry_wait_ns | 48 | 0.1 | Longest host wait on the acquire fence before the one retry of vmafx_context_import_frame() (the import rule, ADR-1929), in nanoseconds: 1 to 600000000000 (10 minutes); 0, the value of VMAFX_CONTEXT_CONFIG_INIT, is the default of 10 seconds. A larger value is refused with VMAFX_E_RANGE naming config.import_retry_wait_ns, not clamped. Added in ABI 0.1.3. |
Initialise with VMAFX_CONTEXT_CONFIG_INIT.
VmafxExtractorInfo¶
One registered feature extractor. Size 16 bytes, alignment 8. Since 0.1.
| Field | C declaration | Offset | Since | Description |
|---|---|---|---|---|
struct_size | uint32_t struct_size | 0 | 0.1 | Size of this struct as the caller compiled it; set by the _INIT macro. |
backend | uint32_t backend | 4 | 0.1 | Backend the extractor runs on. Values: VmafxBackend. |
name | const char *name | 8 | 0.1 | Extractor name (for example psnr, adm_cuda). |
Initialise with VMAFX_EXTRACTOR_INFO_INIT.
VmafxFeatureResolution¶
Which extractor computes a feature on a context (ADR-1359). Strings live for the process lifetime. Size 24 bytes, alignment 8. Since 0.1.
| Field | C declaration | Offset | Since | Description |
|---|---|---|---|---|
struct_size | uint32_t struct_size | 0 | 0.1 | Size of this struct as the caller compiled it; set by the _INIT macro. |
backend | uint32_t backend | 4 | 0.1 | Backend of extractor. Values: VmafxBackend. |
extractor | const char *extractor | 8 | 0.1 | Extractor that computes the feature: the CPU extractor on a context without a device backend, else its device twin. |
unsupported_option | const char *unsupported_option | 16 | 0.1 | The option the twin cannot honour when the call returns VMAFX_E_NOTSUP, else NULL. |
Initialise with VMAFX_FEATURE_RESOLUTION_INIT.
Functions¶
| Function | Since | Description |
|---|---|---|
vmafx_context_create | 0.1 | Create a context. config may be NULL for the defaults; *out is NULL on failure. |
vmafx_context_destroy | 0.1 | Destroy a context. On a nonzero status the context stays valid and may be destroyed again (ADR-1336). |
vmafx_context_extractor_info | 0.1 | Describe registered extractor index; VMAFX_E_NOTFOUND past the last one. |
vmafx_options_set | 0.1 | Set key to value in *options, creating the set when *options is NULL; numeric values are normalised as libvmaf does. The caller owns the set and releases it with vmafx_options_free(). |
vmafx_options_free | 0.1 | Release an option set; NULL is a no-op. |
vmafx_context_set_option | 0.1 | Set a context option: perceptual_weight (0 / 1), perceptual_weight_strength (a finite number >= 0) or check_sample_range (0 / 1; since ABI 0.1.6: refuse a frame pair with a sample above 2^bpc - 1 with VMAFX_E_INVALID, naming its plane, row, column and value; off by default; a device frame cannot be scanned and is VMAFX_E_NOTSUP). VMAFX_E_NOTFOUND names an unknown key, VMAFX_E_INVALID a value the key refuses. |
vmafx_context_use_feature | 0.1 | Register the extractor named extractor with options (copied; may be NULL). VMAFX_E_NOTFOUND names an unknown extractor. |
vmafx_context_use_model | 0.1 | Register the extractors of every feature model reads and mount the model. The context takes a reference to the model until it is destroyed (ADR-1755); the caller may release its own at once. |
vmafx_context_use_model_set | 0.1 | Register the extractors of every member of set and mount the members. The context takes a reference to the set until it is destroyed. |
vmafx_context_import_score | 0.1 | Record value as the score of feature at frame index, computed outside the library. |
vmafx_context_extractor_count | 0.1 | Number of registered feature extractors; 0 for NULL. |
vmafx_feature_resolve | 0.1 | Which extractor would compute the CPU extractor extractor with options (may be NULL) on this context, for frames of frame (may be NULL: no geometry check). On a context without a device backend that is the CPU extractor itself. VMAFX_E_NOTFOUND names an unknown extractor; VMAFX_E_NOTSUP names a device backend without a twin, or the option (and out.unsupported_option) the twin cannot honour (ADR-1359). |
vmafx_context_frame_retention | 0.1 | How many earlier reference frames the context keeps after vmafx_submit() returns: 1 (frame n-1), or 2 when a registered extractor reads frame n-2 (ADR-1478). With worker threads more frames stay in flight until their work finishes: vmafx_context_max_in_flight() gives the bound. 0 for NULL. |
vmafx_submit | 0.1 | Score frame index from reference and distorted. Consumes one reference of each frame on every path, failures included (the same frame as both inputs needs two); a frame submitted to several contexts needs one reference per submit and is never copied. Indices increase strictly and every frame keeps the first frame's geometry. |
vmafx_flush | 0.1 | Finish every submitted frame; scores of the last frames (motion) become final. A context is flushed once; a second flush or a submit after it is VMAFX_E_INVALID. |
vmafx_context_use_device | 0.1 | Score on device: the context picks each feature's twin on its backend and holds a reference to the device until it is destroyed. Call it once, before any feature, model or frame; a device can serve several contexts. A context without a device scores on the CPU. |
vmafx_context_admit | 0.1 | Whether every extractor registered on the context can read frame where it lives, without a host copy (ADR-1688 generalised). VMAFX_E_NOTSUP names each refusing extractor and why; vmafx_submit() makes the same check before it counts a frame. |
vmafx_context_import_frame | 0.1 | Import a frame for context under the import rule (ADR-1852 decision D8): vmafx_frame_import() and vmafx_context_admit(); a transient failure (VMAFX_E_BUSY, VMAFX_E_TIMEOUT) is retried once after a host wait on desc.acquire of at most the context's import_retry_wait_ns (10 seconds by default); a second failure or any other one fails naming the backend, device, input (for example main or reference), memory kind, pixel format, modifiers and the refusing extractors. Never falls back to a host copy. |
vmafx_context_max_in_flight | 0.1 | The most frames of each input the context holds when vmafx_submit() returns, whatever the producer's rate: with R = vmafx_context_frame_retention() and T = n_threads, R + 2 * T * (R + 1), plus 1 on a device backend. Without worker threads a submit scores its frame before it returns (R). With them a submit waits while T frames wait for a worker (backpressure), so at most 2 * T frames are in flight, each holding itself and its R earlier reference frames; a device extractor holds its frame until the next submit collects it. A producer that recycles its frames (a texture ring, a frame pool) needs this many plus the frame it is filling. 0 for NULL. Added in ABI 0.1.8. |
vmafx_context_backend | 0.1 | Backend the context scores on (VmafxBackend): the backend of its device, or of the device state a libvmaf caller imported; CPU for NULL and for a context on the CPU. Added in ABI 0.1.6. |
vmafx_context_preallocate | 0.1 | Let the context allocate count frames of desc once, in the memory its device reads fastest (page-locked host memory for a GPU device state, else host memory), for vmafx_context_acquire_frame(). Checked against the context's frame retention: a count below the depth its extractors keep is VMAFX_E_INVALID, now and when such an extractor is registered later. Added in ABI 0.1.6. |
vmafx_context_acquire_frame | 0.1 | One of the frames vmafx_context_preallocate() made, with one reference the caller holds; waits until a frame is free (one returns when its last reference is dropped). VMAFX_E_INVALID without preallocated frames. Added in ABI 0.1.6. |
vmafx_context_attach_sidedata | 0.1 | Attach the perceptual side data of frame index (a pre-processor's interop blob, ADR-1118) to the context; it weights the frame in pooled scores while the perceptual_weight option is on. A blob of another interop major version is ignored for that frame with a warning and the engine's errno. Added in ABI 0.1.6. |
vmafx_context_set_default_color | 0.1 | The colour of the submitted frames that carry none (every member of their VmafxFrameDesc.color UNKNOWN), per input; NULL leaves that input's default unset. Only a model with a conversion_target reads frame colour: it converts every pair from its colour and refuses a pair whose colour is not fully specified. VMAFX_E_BUSY once a pair has been converted (the conversion is built from the first converted pair's colour), as is a submitted pair whose colour differs from it. Added in ABI 0.1.6. |
VMAFX_EXPORT VmafxStatus vmafx_context_create(const VmafxContextConfig *config, VmafxContext **out,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_destroy(VmafxContext *context, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_extractor_info(const VmafxContext *context, uint32_t index,
VmafxExtractorInfo *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_options_set(VmafxOptions **options, const char *key,
const char *value, VmafxError **error);
VMAFX_EXPORT void vmafx_options_free(VmafxOptions *options);
VMAFX_EXPORT VmafxStatus vmafx_context_set_option(VmafxContext *context, const char *key,
const char *value, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_use_feature(VmafxContext *context, const char *extractor,
const VmafxOptions *options, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_use_model(VmafxContext *context, VmafxModel *model,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_use_model_set(VmafxContext *context, VmafxModelSet *set,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_import_score(VmafxContext *context, const char *feature,
uint64_t index, double value,
VmafxError **error);
VMAFX_EXPORT uint32_t vmafx_context_extractor_count(const VmafxContext *context);
VMAFX_EXPORT VmafxStatus vmafx_feature_resolve(const VmafxContext *context, const char *extractor,
const VmafxOptions *options,
const VmafxFrameDesc *frame,
VmafxFeatureResolution *out, VmafxError **error);
VMAFX_EXPORT uint32_t vmafx_context_frame_retention(const VmafxContext *context);
VMAFX_EXPORT VmafxStatus vmafx_submit(VmafxContext *context, VmafxFrame *reference,
VmafxFrame *distorted, uint64_t index, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_flush(VmafxContext *context, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_use_device(VmafxContext *context, VmafxDevice *device,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_admit(const VmafxContext *context, const VmafxFrame *frame,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_import_frame(VmafxContext *context, VmafxDevice *device,
const VmafxFrameImport *desc, const char *input,
VmafxFrame **out, VmafxError **error);
VMAFX_EXPORT uint32_t vmafx_context_max_in_flight(const VmafxContext *context);
VMAFX_EXPORT uint32_t vmafx_context_backend(const VmafxContext *context);
VMAFX_EXPORT VmafxStatus vmafx_context_preallocate(VmafxContext *context,
const VmafxFrameDesc *desc, uint32_t count,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_acquire_frame(VmafxContext *context, VmafxFrame **out,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_attach_sidedata(VmafxContext *context, uint64_t index,
const void *data, size_t size,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_context_set_default_color(VmafxContext *context,
const VmafxColor *reference,
const VmafxColor *distorted,
VmafxError **error);
Back to the reference index.