io.h

Go to the documentation of this file.

/* Simple Plugin API */
/* SPDX-FileCopyrightText: Copyright © 2018 Wim Taymans */
/* SPDX-License-Identifier: MIT */
 
#ifndef SPA_IO_H
#define SPA_IO_H
 
#include <spa/utils/defs.h>
#include <spa/pod/pod.h>
 
#ifdef __cplusplus
extern "C" {
#endif



enum spa_io_type {
        SPA_IO_Invalid,
        SPA_IO_Buffers,           
        SPA_IO_Range,               
        SPA_IO_Clock,               
        SPA_IO_Latency,           
        SPA_IO_Control,           
        SPA_IO_Notify,             
        SPA_IO_Position, 
        SPA_IO_RateMatch,       
        SPA_IO_Memory,             
        SPA_IO_AsyncBuffers, 
};


struct spa_io_buffers {
#define SPA_STATUS_OK                   0
#define SPA_STATUS_NEED_DATA            (1<<0)
#define SPA_STATUS_HAVE_DATA            (1<<1)
#define SPA_STATUS_STOPPED              (1<<2)
#define SPA_STATUS_DRAINED              (1<<3)
        int32_t status;                   
        uint32_t buffer_id;            
};
 
#define SPA_IO_BUFFERS_INIT  ((struct spa_io_buffers) { SPA_STATUS_OK, SPA_ID_INVALID, })

struct spa_io_memory {
        int32_t status;                   
        uint32_t size;                      
        void *data;                     
};
#define SPA_IO_MEMORY_INIT  ((struct spa_io_memory) { SPA_STATUS_OK, 0, NULL, })

struct spa_io_range {
        uint64_t offset;  
        uint32_t min_size;      
        uint32_t max_size;      
};


 *
 * The clock counts the elapsed time according to the clock provider
 * since the provider was last started.
 *
 * Driver nodes are supposed to update the contents of \ref SPA_IO_Clock before
 * signaling the start of a graph cycle.  These updated clock values become
 * visible to other nodes in \ref SPA_IO_Position. Non-driver nodes do
 * not need to update the contents of their \ref SPA_IO_Clock. Also
 * see \ref page_driver for further details.
 *
 * The host generally gives each node a separate \ref spa_io_clock in \ref
 * SPA_IO_Clock, so that updates made by the driver are not visible in the
 * contents of \ref SPA_IO_Clock of other nodes. Instead, \ref SPA_IO_Position
 * is used to look up the current graph time.
 *
 * A node is a driver when \ref spa_io_clock::id and the ID in
 * \ref spa_io_position.clock in \ref SPA_IO_Position are the same.
 *
 * The flags are set by the graph driver at the start of each cycle.
 */
struct spa_io_clock {
#define SPA_IO_CLOCK_FLAG_FREEWHEEL     (1u<<0) 
#define SPA_IO_CLOCK_FLAG_XRUN_RECOVER  (1u<<1) 
                                                  *  flag is cleared again. That way, the node knows that
                                                  *  during the last cycle it experienced an xrun. They
                                                  *  can use this information for example to resynchronize
                                                  *  or clear custom stale states. */
#define SPA_IO_CLOCK_FLAG_LAZY          (1u<<2) 
#define SPA_IO_CLOCK_FLAG_NO_RATE       (1u<<3) 
#define SPA_IO_CLOCK_FLAG_DISCONT       (1u<<4) 
        uint32_t flags;                    
        uint32_t id;                  
        char name[64];                  
        uint64_t nsec;                      
        struct spa_fraction rate;       
        uint64_t position;              
        uint64_t duration;              
        int64_t delay;                     
        double rate_diff;              
        uint64_t next_nsec;            
 
        struct spa_fraction target_rate; 
        uint64_t target_duration;                
        uint32_t target_seq;                  
        uint32_t cycle;                    
        uint64_t xrun;                      
};
 
/* the size of the video in this cycle */
struct spa_io_video_size {
#define SPA_IO_VIDEO_SIZE_VALID         (1<<0)
        uint32_t flags;                    
        uint32_t stride;          
        struct spa_rectangle size;     
        struct spa_fraction framerate;  
        uint32_t padding[4];
};


struct spa_io_latency {
        struct spa_fraction rate;       
        uint64_t min;                        
        uint64_t max;                        
};

struct spa_io_sequence {
        struct spa_pod_sequence sequence;       
};

struct spa_io_segment_bar {
#define SPA_IO_SEGMENT_BAR_FLAG_VALID           (1<<0)
        uint32_t flags;                    
        uint32_t offset;          
        float signature_num;               
        float signature_denom;           
        double bpm;                  
        double beat;                        
        double bar_start_tick;
        double ticks_per_beat;
        uint32_t padding[4];
};

/** video frame segment */
struct spa_io_segment_video {
#define SPA_IO_SEGMENT_VIDEO_FLAG_VALID         (1<<0)
#define SPA_IO_SEGMENT_VIDEO_FLAG_DROP_FRAME    (1<<1)
#define SPA_IO_SEGMENT_VIDEO_FLAG_PULL_DOWN     (1<<2)
#define SPA_IO_SEGMENT_VIDEO_FLAG_INTERLACED    (1<<3)
        uint32_t flags;                    
        uint32_t offset;          
        struct spa_fraction framerate;
        uint32_t hours;
        uint32_t minutes;
        uint32_t seconds;
        uint32_t frames;
        uint32_t field_count;                
        uint32_t padding[11];
};


 * The segment position is valid when the current running time is between
 * start and start + duration. The position is then
 * calculated as:
 *
 *   (running time - start) * rate + position;
 *
 * Support for looping is done by specifying the LOOPING flags with a
 * non-zero duration. When the running time reaches start + duration,
 * duration is added to start and the loop repeats.
 *
 * Care has to be taken when the running time + clock.duration extends
 * past the start + duration from the segment; the user should correctly
 * wrap around and partially repeat the loop in the current cycle.
 *
 * Extra information can be placed in the segment by setting the valid flags
 * and filling up the corresponding structures.
 */
struct spa_io_segment {
        uint32_t version;
#define SPA_IO_SEGMENT_FLAG_LOOPING     (1<<0)  
#define SPA_IO_SEGMENT_FLAG_NO_POSITION (1<<1)  
        uint32_t flags;                            
        uint64_t start;                         
        uint64_t duration;                      
        double rate;                                
        uint64_t position;                      
 
        struct spa_io_segment_bar bar;
        struct spa_io_segment_video video;
};
 
enum spa_io_position_state {
        SPA_IO_POSITION_STATE_STOPPED,
        SPA_IO_POSITION_STATE_STARTING,
        SPA_IO_POSITION_STATE_RUNNING,
};

#define SPA_IO_POSITION_MAX_SEGMENTS    8


 */
struct spa_io_position {
        struct spa_io_clock clock;             
        struct spa_io_video_size video;           
        int64_t offset;                           
        uint32_t state;                            
 
        uint32_t n_segments;                  
        struct spa_io_segment segments[SPA_IO_POSITION_MAX_SEGMENTS]; 
};

 *
 * When resampling to (graph->node) direction, the number of samples produced
 * by the resampler varies on each cycle, as the rates are not commensurate.
 *
 * When resampling to (node->graph) direction, the number of samples consumed by the
 * resampler varies. Node output ports in process() should produce \a size number of
 * samples to match what the resampler needs to produce one graph quantum of output
 * samples.
 *
 * Resampling filters introduce processing delay, given by \a delay and \a delay_frac, in
 * samples at node rate. The delay varies on each cycle e.g. when resampling between
 * noncommensurate rates.
 *
 * The first sample output (graph->node) or consumed (node->graph) by the resampler is
 * offset by \a delay + \a delay_frac / 1e9 node samples relative to the nominal graph
 * cycle start position:
 *
 * \code{.unparsed}
 * first_resampled_sample_nsec =
 *      first_original_sample_nsec
 *      - (rate_match->delay * SPA_NSEC_PER_SEC + rate_match->delay_frac) / node_rate
 * \endcode
 */
struct spa_io_rate_match {
        uint32_t delay;                    
        uint32_t size;                      
        double rate;                        
#define SPA_IO_RATE_MATCH_FLAG_ACTIVE   (1 << 0)
        uint32_t flags;                    
        int32_t delay_frac;           
        uint32_t padding[6];
};

struct spa_io_async_buffers {
        struct spa_io_buffers buffers[2];  
};

 
#ifdef __cplusplus
}  /* extern "C" */
#endif
 
#endif /* SPA_IO_H */