vmafx/score.h¶
Frame scores, pooled scores and windows.
#include <vmafx/score.h>.
VmafxWindowTarget¶
What a window pools. Added in ABI 0.1.8. Since 0.1.
| Constant | Value | Since |
|---|---|---|
VMAFX_WINDOW_TARGET_NONE | 0 | 0.1 |
VMAFX_WINDOW_TARGET_MODEL | 1 | 0.1 |
VMAFX_WINDOW_TARGET_MODEL_SET | 2 | 0.1 |
VMAFX_WINDOW_TARGET_FEATURE | 3 | 0.1 |
VmafxPoolMask¶
A set of pooling methods: bit 1 << p for each VmafxPool p. Bit 0 (VMAFX_POOL_NONE) is not a method. Added in ABI 0.1.8. Bits of a u32 field. Since 0.1.
| Constant | Bit | Since | Meaning |
|---|---|---|---|
VMAFX_POOL_MASK_MIN | 1 | 0.1 | VMAFX_POOL_MIN. |
VMAFX_POOL_MASK_MAX | 2 | 0.1 | VMAFX_POOL_MAX. |
VMAFX_POOL_MASK_MEAN | 3 | 0.1 | VMAFX_POOL_MEAN. |
VMAFX_POOL_MASK_HARMONIC_MEAN | 4 | 0.1 | VMAFX_POOL_HARMONIC_MEAN. |
VMAFX_POOL_MASK_MEDIAN | 5 | 0.1 | VMAFX_POOL_MEDIAN. |
VMAFX_POOL_MASK_PERC5 | 6 | 0.1 | VMAFX_POOL_PERC5. |
VMAFX_POOL_MASK_PERC10 | 7 | 0.1 | VMAFX_POOL_PERC10. |
VMAFX_POOL_MASK_PERC20 | 8 | 0.1 | VMAFX_POOL_PERC20. |
VmafxWindowFlags¶
What is true of a window result or a window span. Added in ABI 0.1.8. Bits of a u32 field. Since 0.1.
| Constant | Bit | Since | Meaning |
|---|---|---|---|
VMAFX_WINDOW_PARTIAL | 0 | 0.1 | The stream ended inside the window: a result pooled fewer frames than it asked for (the context was flushed before frame last); a span is the last window of the stream, cut off by vmafx_window_clock_finish(). |
Handles and callbacks¶
| Type | Since | Description |
|---|---|---|
VmafxWindow | 0.1 | An asynchronous pooled score over a range of frames (vmafx_window_submit()). Owns its result until released. Added in ABI 0.1.8. Released by vmafx_window_release. |
VmafxWindowClock | 0.1 | Cuts a stream of frames into windows of n_stats seconds or n_stats_frames frames (#2138). Holds no context; one per stream. Added in ABI 0.1.8. Released by vmafx_window_clock_destroy. |
VmafxWindowCallback | 0.1 | Called once when a window completes, on the context's callback thread (a library thread, never the caller's, apart from the completion thread so a slow callback holds up no window), in completion order. result is valid during the call; the same result stays readable with vmafx_window_poll(). It may call vmafx_window_poll(), vmafx_window_wait() and vmafx_window_release() (also on its own window) and must not call any other function on the window's context: no vmafx_submit(), no vmafx_flush(). Added in ABI 0.1.8. |
typedef void (*VmafxWindowCallback)(VmafxWindow *window, const VmafxWindowResult *result,
void *user);
Structs¶
VmafxScore¶
One score and the extractor that produced it. Size 40 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 the producing extractor (CPU when none is registered). Values: VmafxBackend. |
index | uint64_t index | 8 | 0.1 | Frame index. |
value | double value | 16 | 0.1 | Score. |
feature | const char *feature | 24 | 0.1 | Feature name as requested. |
extractor | const char *extractor | 32 | 0.1 | Registered extractor that wrote the feature (option-decorated names included, RC4 WP5), or NULL (imported and model scores); vmafx_feature_provenance() describes it. |
Initialise with VMAFX_SCORE_INIT.
VmafxPooledScore¶
A score pooled over a range of frames. Size 40 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. |
pool | uint32_t pool | 4 | 0.1 | Pooling method. Values: VmafxPool. |
first | uint64_t first | 8 | 0.1 | First frame index (inclusive). |
last | uint64_t last | 16 | 0.1 | Last frame index (inclusive). |
value | double value | 24 | 0.1 | Pooled score. |
feature | const char *feature | 32 | 0.1 | The model's name (lives as long as the model) or the feature argument as passed. |
Initialise with VMAFX_POOLED_SCORE_INIT.
VmafxModelSetScore¶
The bootstrap score of a model set at one frame or pooled over frames. Size 64 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. |
pool | uint32_t pool | 4 | 0.1 | Pooling method; VMAFX_POOL_NONE for a per-frame score. Values: VmafxPool. |
first | uint64_t first | 8 | 0.1 | First frame index (the frame of a per-frame score). |
last | uint64_t last | 16 | 0.1 | Last frame index (inclusive). |
bagging | double bagging | 24 | 0.1 | Mean of the member models' scores. |
stddev | double stddev | 32 | 0.1 | Standard deviation of the member models' scores. |
ci95_lo | double ci95_lo | 40 | 0.1 | Lower bound of the 95% confidence interval. |
ci95_hi | double ci95_hi | 48 | 0.1 | Upper bound of the 95% confidence interval. |
name | const char *name | 56 | 0.1 | Name of the model set; lives as long as the set. |
Initialise with VMAFX_MODEL_SET_SCORE_INIT.
VmafxWindowRequest¶
A window to pool. Initialise with VMAFX_WINDOW_REQUEST_INIT. Added in ABI 0.1.8. Size 72 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. |
target | uint32_t target | 4 | 0.1 | What to pool; the matching one of model, model_set and feature is set, the other two are ignored. Values: VmafxWindowTarget. |
pool_mask | uint32_t pool_mask | 8 | 0.1 | Pooling methods, at least one. Bits: VmafxPoolMask. |
first | uint64_t first | 16 | 0.1 | First frame index (inclusive). |
last | uint64_t last | 24 | 0.1 | Last frame index (inclusive), at most 4294967295 (the engine's frame index). |
model | const VmafxModel *model | 32 | 0.1 | The model of a MODEL window; the window holds a reference until it is released. |
model_set | const VmafxModelSet *model_set | 40 | 0.1 | The model set of a MODEL_SET window; the window holds a reference until it is released. |
feature | const char *feature | 48 | 0.1 | The feature of a FEATURE window, as vmafx_feature_score_pooled() names it (copied). |
on_complete | VmafxWindowCallback on_complete | 56 | 0.1 | Called once when the window completes; NULL: observe completion with vmafx_window_poll() or vmafx_window_wait(). |
user | void *user | 64 | 0.1 | Passed to on_complete. |
Initialise with VMAFX_WINDOW_REQUEST_INIT.
VmafxWindowResult¶
The scores of a completed window. Each value is the synchronous call's (vmafx_score_pooled(), vmafx_feature_score_pooled(), vmafx_score_pooled_model_set()) over frames first to first + n_frames - 1, bit for bit: both run one pooling implementation. Initialise with VMAFX_WINDOW_RESULT_INIT. Added in ABI 0.1.8. Size 352 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. |
status | VmafxStatus status | 4 | 0.1 | VMAFX_OK when every requested method has its value; otherwise why the window has none, for example VMAFX_E_RANGE when no scored frame of the window was in the stream, VMAFX_E_NOTFOUND when its feature or a feature its model reads was never scored, VMAFX_E_INVALID when the context was destroyed first. The failure is also logged to the context. |
flags | uint32_t flags | 8 | 0.1 | VMAFX_WINDOW_PARTIAL when the stream ended before frame last. Bits: VmafxWindowFlags. |
target | uint32_t target | 12 | 0.1 | What the window pooled. Values: VmafxWindowTarget. |
pool_mask | uint32_t pool_mask | 16 | 0.1 | The requested methods; value[p] is set for each bit 1 << p. Bits: VmafxPoolMask. |
first | uint64_t first | 24 | 0.1 | First frame index, as requested. |
last | uint64_t last | 32 | 0.1 | Last frame index, as requested. |
n_frames | uint64_t n_frames | 40 | 0.1 | Frames pooled over: last - first + 1, fewer for a partial window. |
n_scored | uint64_t n_scored | 48 | 0.1 | Frames of those the context scored (every n_subsample-th index) and the values summarise. |
value | double value[9] | 56 | 0.1 | Indexed by VmafxPool: the pooled score of each requested method (the bagging score for a model set); 0 elsewhere. |
stddev | double stddev[9] | 128 | 0.1 | MODEL_SET windows: the pooled standard deviation per method; 0 otherwise. |
ci95_lo | double ci95_lo[9] | 200 | 0.1 | MODEL_SET windows: the pooled lower bound of the 95% confidence interval per method; 0 otherwise. |
ci95_hi | double ci95_hi[9] | 272 | 0.1 | MODEL_SET windows: the pooled upper bound of the 95% confidence interval per method; 0 otherwise. |
name | const char *name | 344 | 0.1 | The model's name, the model set's name or the feature; lives as long as the window. |
Initialise with VMAFX_WINDOW_RESULT_INIT.
VmafxWindowClockConfig¶
Window length of a VmafxWindowClock: exactly one of the two is set, as the window option group's n_stats and n_stats_frames (#2138). Initialise with VMAFX_WINDOW_CLOCK_CONFIG_INIT. Added in ABI 0.1.8. 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. |
n_stats | double n_stats | 8 | 0.1 | Window length in seconds, finite and above 0, rounded to whole nanoseconds (at least 1); 0: windows by frame count. Window k holds the frames whose presentation time lies in [t0 + k * n_stats, t0 + (k + 1) * n_stats), t0 the first frame's. |
n_stats_frames | uint64_t n_stats_frames | 16 | 0.1 | Window length in frames; 0: windows by time. Window k holds the frames whose index lies in [i0 + k * n_stats_frames, i0 + (k + 1) * n_stats_frames), i0 the first frame's. |
Initialise with VMAFX_WINDOW_CLOCK_CONFIG_INIT.
VmafxWindowSpan¶
One window of a stream as a VmafxWindowClock cut it: submit first to last with vmafx_window_submit(). Initialise with VMAFX_WINDOW_SPAN_INIT. Added in ABI 0.1.8. 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. |
flags | uint32_t flags | 4 | 0.1 | VMAFX_WINDOW_PARTIAL for the last window of the stream when the stream ended inside it. Bits: VmafxWindowFlags. |
window | uint64_t window | 8 | 0.1 | Window number k. Windows without a frame (a gap in the stream) are skipped, so numbers can jump. |
first | uint64_t first | 16 | 0.1 | Index of the window's first frame. |
last | uint64_t last | 24 | 0.1 | Index of the window's last frame. |
n_frames | uint64_t n_frames | 32 | 0.1 | Frames the clock saw in the window. |
start_ns | int64_t start_ns | 40 | 0.1 | Windows by time: the window's start, t0 + k * n_stats, in the stream's nanoseconds. Windows by frame count: the presentation time of its first frame. |
end_ns | int64_t end_ns | 48 | 0.1 | Windows by time: the window's end, t0 + (k + 1) * n_stats (exclusive). Windows by frame count: the presentation time of its last frame. |
Initialise with VMAFX_WINDOW_SPAN_INIT.
Functions¶
| Function | Since | Description |
|---|---|---|
vmafx_feature_score | 0.1 | Score of feature at frame index with its producer; VMAFX_PENDING while the frame is not final. |
vmafx_score_frame | 0.1 | Score of model at frame index, predicted on first read; VMAFX_PENDING while a feature it reads is not final. |
vmafx_score_frame_model_set | 0.1 | Bootstrap score of set at frame index; VMAFX_PENDING while a feature it reads is not final. |
vmafx_score_pooled | 0.1 | Score of model pooled with pool (a VmafxPool) over frames first to last (inclusive, subsampled frames skipped); VMAFX_PENDING where vmaf_score_pooled() returns -EAGAIN. |
vmafx_feature_score_pooled | 0.1 | Scores of feature pooled as vmafx_score_pooled() does. |
vmafx_score_pooled_model_set | 0.1 | Bootstrap score of set with each of its four values pooled with pool over frames first to last. |
vmafx_window_submit | 0.1 | Ask for request.target pooled with every method of request.pool_mask over frames first to last, and return at once. The window completes when every scored frame of its range is final, or at vmafx_flush(), which completes it over the frames the stream had and flags it VMAFX_WINDOW_PARTIAL when the stream ended before last. A device backend collects a frame's scores one submit later. motion2 / motion3 of a frame, and so every VMAF model, are final once the frame after it is scored (ADR-2090); the last frame's at vmafx_flush(). The context's completion thread (started by its first window) finds completion: the worker that finishes a frame, a submit, a flush, an import and this call wake it, so a window completes whether or not the feeding thread calls again; a window already final completes right after this call. At most 1024 windows of a context are open; one more is VMAFX_E_BUSY naming context. The caller holds the window until vmafx_window_release(). Added in ABI 0.1.8. |
vmafx_window_poll | 0.1 | VMAFX_OK and the result when the window has completed, VMAFX_PENDING (no error, out untouched) while it has not. Thread-safe: may run on any thread while the context is in use. A completed window's own failure is in out.status, not in the return value. Added in ABI 0.1.8. |
vmafx_window_wait | 0.1 | vmafx_window_poll() after waiting up to timeout_ns nanoseconds for the window to complete (UINT64_MAX: without a limit); VMAFX_PENDING, without an error, when it has not by then. Thread-safe, also on the thread that feeds the context: the completion thread completes the window. Added in ABI 0.1.8. |
vmafx_window_release | 0.1 | Release the caller's window, completed or not. An open window is cancelled: its callback never runs. A callback of the window running on the callback thread is waited for, unless this call is made from that callback. Thread-safe; NULL is a no-op. Added in ABI 0.1.8. |
vmafx_window_clock_create | 0.1 | A clock that cuts a stream into windows of config.n_stats seconds or config.n_stats_frames frames (#2138). Both set, neither set, or n_stats negative, not finite or below 1 ns is VMAFX_E_INVALID naming the field. Added in ABI 0.1.8. |
vmafx_window_clock_frame | 0.1 | Tell the clock frame index at presentation time pts_ns. When the frame lies past the open window, that window is complete: VMAFX_OK, its span in out, and the frame opens the next window. Otherwise VMAFX_PENDING (no error, out untouched). Indices increase strictly and times never decrease, else VMAFX_E_INVALID naming index or pts_ns. Added in ABI 0.1.8. |
vmafx_window_clock_finish | 0.1 | End of stream: VMAFX_OK and the span of the open window, flagged VMAFX_WINDOW_PARTIAL unless it is a full window by frame count; VMAFX_PENDING (no error, out untouched) when no window is open. Afterwards the clock takes no more frames. Added in ABI 0.1.8. |
vmafx_window_clock_destroy | 0.1 | Free the clock. NULL is a no-op. Added in ABI 0.1.8. |
VMAFX_EXPORT VmafxStatus vmafx_feature_score(VmafxContext *context, const char *feature,
uint64_t index, VmafxScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_score_frame(VmafxContext *context, const VmafxModel *model,
uint64_t index, VmafxScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_score_frame_model_set(VmafxContext *context,
const VmafxModelSet *set, uint64_t index,
VmafxModelSetScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_score_pooled(VmafxContext *context, const VmafxModel *model,
uint32_t pool, uint64_t first, uint64_t last,
VmafxPooledScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_feature_score_pooled(VmafxContext *context, const char *feature,
uint32_t pool, uint64_t first, uint64_t last,
VmafxPooledScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_score_pooled_model_set(VmafxContext *context,
const VmafxModelSet *set, uint32_t pool,
uint64_t first, uint64_t last,
VmafxModelSetScore *out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_window_submit(VmafxContext *context,
const VmafxWindowRequest *request, VmafxWindow **out,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_window_poll(const VmafxWindow *window, VmafxWindowResult *out,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_window_wait(const VmafxWindow *window, uint64_t timeout_ns,
VmafxWindowResult *out, VmafxError **error);
VMAFX_EXPORT void vmafx_window_release(VmafxWindow *window);
VMAFX_EXPORT VmafxStatus vmafx_window_clock_create(const VmafxWindowClockConfig *config,
VmafxWindowClock **out, VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_window_clock_frame(VmafxWindowClock *clock, uint64_t index,
int64_t pts_ns, VmafxWindowSpan *out,
VmafxError **error);
VMAFX_EXPORT VmafxStatus vmafx_window_clock_finish(VmafxWindowClock *clock, VmafxWindowSpan *out,
VmafxError **error);
VMAFX_EXPORT void vmafx_window_clock_destroy(VmafxWindowClock *clock);
Back to the reference index.