proc-id.hpp File Reference

Metadata interface to generate symbolic and hash ID tags for media processing steps. More...

Go to the source code of this file.

Description

Metadata interface to generate symbolic and hash ID tags for media processing steps.

Functionality is provided to identify a point in the processing chain for sake of error reporting and unit testing; moreover, identifying information can be chained and combined into a systematic hash key, to serve as foundation for a stable cache key.

Warning

The specification expresses semantic distinctions and it is the responsibility of the media-processing-library binding plug-in to ensure that classification matches relevant semantic distinctions. In this context, "different" means that two functions produce perceptibly different results — which also implies that for equivalent IDs we can use cached calculation results.

Code arrangement

• proc-node.hpp is a shallow interface header (included rather widely)
• proc-id.hpp (this header) details node specifications and is used for the NodeBuidler
• proc-node.cpp acts as »module« and anchor for all implementation services

Structure and syntax

A complete processing-specification combines a high-level identification of the enclosing Node with qualifiers to describe a specific functionality variant for a given Port, together with the structure of the input and output argument lists, and a set of additional, extended attributes. Any aspects should be recorded here, if they might cause differences in computed results or are relevant for some further information function (used for diagnostic, engine instrumentation and job planning)

• the Node symbol is related to the processing asset and is expected to be structured as <ontology>:<semanticID>, e.g. FFmpeg:gaussianBlur
• the Port qualifier accounts for specific configuration applied for the given port
• the Argument lists should follow the pattern [(inType, ...)](outType,...), with the allowed shorthand notation <type>/N to designate N identical arguments of type type. For a complete processing spec, the node symbol is possible decorated with a dot and the port qualifier (if present), then followed by the argument lists.

Hash computation

Hash-IDs are derived from the full processing spec,_ but also from individual parts alone for some use cases (e.g. dispatch of information functions). Furthermore, the Hash-IDs of all Nodes in a processing chain can be combined into a Hash-ID of the chain, which is usable as cache key: when the hash-ID matches, a cached result can be used instead of re-computation.

Todo:

Can we assume size_t == 64bit; is this enough to prevent collisions? Can we afford using a 128bit hash? What about portability of hash values?

WIP-WIP as of 10/2024 this is a draft created as an aside while working towards the first integration of render engine functionality //////////////////////////////////////////////TICKET #1377 : establish a systematic processing identification

Remarks

the essential requirement for a systematic and stable cache key is

• to be be re-generated directly from the render node network
• to be differing if and only if the underlying processing structure changes

See also

turnout.hpp

engine::ProcNodeDiagnostic

proc-node.cpp for the implementation backend

Definition in file proc-id.hpp.

#include "lib/error.hpp"
#include "lib/hash-standard.hpp"
#include "lib/several.hpp"
#include "lib/nocopy.hpp"
#include <utility>
#include <string>

Namespaces
namespace	steam
	Steam-Layer implementation namespace root.
namespace	steam::engine
	Lumiera's render engine core and operational control.

Typedefs
using	StrView = std::string_view

Classes
struct	ProcAttrib
	Extended Attributes for ProcID metadata. More...
class	ProcID
	Metadata to qualify a Port (and implicitly the enclosing Node). More...
struct	ProcID::ArgModel
	Expanded information regarding node input and output. More...