Struct PyTransform 

pub struct PyTransform { /* private fields */ }

A gst-python-ml element hosted as a first-class g2g transform.

Implementations

impl PyTransform

pub fn new(module: impl Into<String>, class: impl Into<String>) -> Self

Host the class from Python module. The instance is created at configure_pipeline time (under the GIL), not here, so construction stays cheap and infallible like the other elements’ new.

pub fn with_accept(self, caps: Caps) -> Self

Override the accepted sink caps (e.g. to host an NV12 element). The supported set may carry Any dims/rate: negotiation fixes them against concrete upstream caps, so process always sees a fixed format.

pub fn with_produce(self, caps: Caps) -> Self

Emit caps downstream instead of the negotiated input caps, for a hosted element that changes media type.

pub fn with_draw_label(self, on: bool) -> Self

Set the draw-label overlay flag forwarded to the Python task.

pub fn with_cuda_frames(self, on: bool) -> Self

Host an element that works on GPU-resident CUDA frames: they reach it as __cuda_array_interface__ planes through g2g_process_cuda and flow on still device-resident. Sets this element’s whole memory-domain story (see AsyncElement::input_domains); the hosted class must define g2g_process_cuda and the caps must be semi-planar (NV12 / P010).

pub fn emitted_count(&self) -> u64

Count of frames pushed downstream. Useful in tests.

Trait Implementations

impl AsyncElement for PyTransform

fn caps_constraint_as_transform(&self) -> CapsConstraint<'_>

The hosted element reads and writes the frame in place, so the output caps equal the input (when it is in the accepted set) unless output-caps= declared a different media type. Declaring this native constraint (rather than the default legacy intercept-only path, whose output the solver leaves unconstrained) lets the graph solver derive this element’s output edge and lets the runtime forward-caps resolve steer a mid-stream CapsChanged (e.g. an upstream decoder’s first-frame caps) cleanly through it, instead of stalling on an unconstrained boundary.

fn is_format_boundary(&self) -> bool

A hosted element that declares output-caps= turns one media type into another (audio into a transcript), which is what a boundary is.

fn propose_output_caps(&self, input: &Caps) -> Caps

The legacy-bridge half of the constraint above, for the runner paths that derive a boundary element’s output side through this hook.

fn input_domains(&self) -> DomainSet

The hosted element reads the frame where it already is and forwards it untouched, so the domain it emits is the domain it consumes: System bytes over the buffer protocol, or CUDA device memory over __cuda_array_interface__ under cuda-frames. Declaring one domain on both pads keeps that relation honest, so the domain-converter auto-plug splices a download / upload ahead of this element when upstream cannot deliver what the hosted code reads, and splices nothing after it (the frame really does leave in the declared domain).

fn propose_allocation(&self, caps: &Caps) -> Option<AllocationParams>

Ask upstream to allocate in the domain the hosted code can read, so a multi-domain producer (an NVDEC that can keep frames on the device or download them) settles on it rather than needing a converter node. Only the domain is constrained: this element allocates nothing of its own, so it imposes no buffer count or alignment, and the size is one frame.

type ProcessFuture<'a> = Pin<Box<dyn Future<Output = Result<(), G2gError>> + 'a>> where Self: 'a

fn intercept_caps(&self, upstream_caps: &Caps) -> Result<Caps, G2gError>

fn output_memory(&self) -> MemoryDomainKind

The memory domain of the frames this element emits on its output pad. Default System; a GPU producer (a hardware decoder emitting into VRAM, a wgpu/CUDA bridge) overrides it. Surfaced per edge by the negotiate-only path so the DOT dump can mark the GPU / zero-copy links (it is not part of Caps; see DESIGN.md 4.13.9).

fn configure_pipeline( &mut self, absolute_caps: &Caps, ) -> Result<ConfigureOutcome, G2gError>

fn process<'a>( &'a mut self, packet: PipelinePacket, out: &'a mut dyn OutputSink, ) -> Self::ProcessFuture<'a>

fn metadata(&self) -> ElementMetadata

Static introspection metadata for this element type (M178): the gst-inspect “Factory Details” (long-name / classification / description / author). Default: empty, like properties. An element overrides it with a const ElementMetadata to document itself.

fn properties(&self) -> &'static [PropertySpec]

The runtime properties this element type exposes (M104), the GObject property-spec analog. Default: none. An element overrides this (and set_property / get_property) to be settable by name from a gst-launch pipeline or inspectable by a gst-inspect dump. The with_* builders remain the zero-cost construction path; this is the string-keyed runtime face.

fn set_property( &mut self, name: &str, value: PropValue, ) -> Result<(), PropError>

Set a property by name (M104). Default: every name is PropError::Unknown (no properties). An overriding element validates the value kind against its properties spec and applies it.

fn get_property(&self, name: &str) -> Option<PropValue>

Read a property back by name (M104). Default: None. Overriding elements return the current value for a known property.

fn configure_output(&mut self, _output_caps: &Caps) -> Result<(), G2gError>

Receive this element’s negotiated OUTPUT (source-pad) caps after the solve, alongside the input caps from [configure_pipeline] (M185). A geometry / format / rate-changing transform (videoscale, videoconvert, audioresample) uses this to take its target from a downstream capsfilter instead of its own properties, the gst caps-driven idiom. Default: no-op, so elements that don’t need it (and runners that don’t yet deliver it) are unaffected. Called only on transforms, with their single output link’s caps; sources and sinks never receive it.

fn latency(&self) -> LatencyReport

This element’s contribution to the pipeline latency query (M12). Default: zero, non-live. Transforms that buffer (jitter buffers, reorder queues) and live sources override this; the linear runners fold the chain into RunStats::latency.

fn output_domains(&self) -> DomainSet

The full set of memory domains this element can emit on its output pad, not just its preferred one. The producer-capability half of the M351 two-sided allocation-domain negotiation: the runner intersects it with the downstream consumers’ acceptance set and settles on a single domain, so a decoder that can deliver to System or stay resident on the GPU lets the runner keep the frame copy-free when a downstream wants it. Default: just output_memory, so a single-domain element negotiates exactly as before. A multi-domain producer overrides this.

fn configure_allocation(&mut self, _params: &AllocationParams)

Receive the downstream peer’s allocation proposal (M12) so this element can allocate its output buffers from a compatible pool. Default: ignore and allocate however the element sees fit.

fn provide_clock(&self) -> Option<ClockCandidate>

Offer a clock to the pipeline’s clock election (M12). Default: none. Elements that pace to real hardware (an audio sink to its DAC) override this; the runner elects the highest-priority offered clock.

fn set_clock_sync(&mut self, _sync: ClockSync)

Receive the pipeline’s elected clock + base time after election, so a sink can present each frame at its running-time deadline (PTS mapped through the active Segment) — the “use PTS to decide when to display” path. The runner calls this once before streaming, only when a clock was elected. Default: ignore (present as fast as backpressure allows, the pre-sync behaviour). See ClockSync.

fn take_qos(&mut self) -> Option<QosMessage>

Take any QoS signal this element wants to send upstream, consuming it. A synchronising sink that dropped a late frame returns a QosMessage here; the runner forwards it onto the element’s incoming link, where the producer observes it as PushOutcome::Qos. Called by the runner after each process. Default: nothing to send.

fn presentation_stats(&self) -> Option<PresentationStats>

Cumulative presentation counters a paced sink kept over the run, read by the runner once its arm ends and surfaced in RunStats::per_element. A display / audio sink that counts what it actually presented overrides this. Default: not a presenting sink.

fn take_reconfigure(&mut self) -> Option<Reconfigure>

Take any Reconfigure this element wants to send upstream, consuming it. The sink/transform analog of Self::take_qos: the runner forwards it onto the element’s incoming link, where the producer observes it as PushOutcome::Reconfigure. The keyframe-request path uses this: a WebRTC egress sink that received a remote PLI returns Reconfigure::ForceKeyframe so the upstream encoder emits an IDR. Called by the runner after each process. Default: nothing to send.

fn take_bitrate(&mut self) -> Option<u32>

Take a target send bitrate (bits/second) this element wants to push upstream, consuming it. A WebRTC egress sink returns its latest congestion-control / BWE estimate here; the runner forwards it onto the incoming link, where the encoder observes it as PushOutcome::Bitrate and retargets. Called by the runner after each process. Default: none.

fn handles_keyframe_requests(&self) -> bool

Whether this element consumes a downstream keyframe request (PushOutcome::Reconfigure(ForceKeyframe)) itself, i.e. it is an encoder that forces an IDR. Default false: the runner then relays the request onto the element’s input link (M720), so a PLI crosses any number of pass-through transforms (a parser between the encoder and a WebRTC sink) to reach the encoder.

fn handles_bitrate_requests(&self) -> bool

As Self::handles_keyframe_requests, for a downstream bitrate target (PushOutcome::Bitrate): an encoder that retargets returns true.

fn absorbs_orientation(&self) -> bool

Whether this sink applies an OrientationMeta itself, i.e. it can turn the picture for free at present time. The runner sends Reconfigure::AbsorbOrientation up this sink’s input link before the first frame is pulled, so a videoflip upstream attaches the descriptor instead of remapping pixels. Default false: the flip realizes the rotation as it always did.

fn handles_orientation(&self) -> bool

Whether Reconfigure::AbsorbOrientation stops at this element instead of being relayed toward the source. true for videoflip, which answers it by switching to the descriptor, and for any transform whose output geometry is chosen in the buffer’s stored coordinates (a crop), which would mean something different once the picture is turned. Default false: the advertisement crosses.

fn handles_qos(&self) -> bool

Whether this element acts on a downstream QoS report itself, ie it sheds work when the sink is behind (a decoder skipping non-reference frames). Default false: the runner relays the report onto the element’s input link (M175) so it reaches the source, and process never sees it. true surfaces it as PushOutcome::Qos from the element’s own push instead, and the relay stops here.

fn meta_requests(&self) -> MetaRequests

The per-frame metadata this element wants attached to the frames it receives (M976), the pull half of meta_transform’s push half. The runner unions the declaration into the allocation cascade travelling upstream, so a producer any number of hops away can ask MetaRequests::wants in configure_allocation and skip work nobody downstream reads. Default: nothing requested, and a graph where every element defaults cascades exactly as it did before the hook existed.

fn caps_constraint_as_sink(&self) -> CapsConstraint<'_>

M16 step 5b: declare this element’s negotiation-time constraint when used as the sink of a chain. The default returns the legacy bridge (LegacySink wrapping today’s intercept_caps). Migrated sinks override with Accepts(CapsSet) (or a more elaborate native variant) to participate in arc consistency and skip the dynamic intercept callback.

fn caps_preferences(&self) -> Option<CapsPreferences>

What this element is willing to pay for each alternative of the set its caps_constraint_as_* advertises. Default None: the alternatives are already in preference order and cost their index. An element overrides this to declare equal cost between alternatives it does not care about (so a neighbour’s preference decides) or a gap wide enough that a neighbour’s preference cannot pull the chain onto its fallback.

fn set_instance_name(&mut self, _name: String)

Receive this instance’s log name (M179), assigned by the runner as <category>N. Default: ignore. An element that logs about itself stores it and returns it from its LogSource so its log lines carry the instance name.

fn set_log_category(&mut self, _category: String)

Override this instance’s log category (M845), which is otherwise the element type name. Default: ignore. An element that logs about itself stores it (in a LogName) and returns it from LogSource::log_category_override, so G2G_DEBUG filtering keys off the override for this instance while its siblings keep the type category.

fn log_category(&self) -> &'static str

The log category for this element (M179): its short type name by default, the G2G_DEBUG filtering key. A wrapper that erases another element forwards the inner one’s category instead.

impl Debug for PyTransform

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PadTemplates for PyTransform

fn pad_templates() -> Vec<PadTemplate>

Advertise the default accepted format (RGBA, any geometry) on both pads for gst-inspect / autoplug. A pyelement is a same-format transform, so sink and source carry the same set. (with_accept can host another format programmatically; the launch template reflects the default.)

fn pad_template(direction: PadDirection) -> Option<PadTemplate>

The first pad template in the given direction, if any.