From d0aff793b76d29f399be239015490036cea3b7d4 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 24 May 2021 18:57:00 +1000 Subject: [PATCH] spa: doxygenize the param/video comments --- spa/include/spa/param/video/chroma.h | 23 ++-- spa/include/spa/param/video/color.h | 134 +++++++-------------- spa/include/spa/param/video/multiview.h | 151 +++++++++++------------- spa/include/spa/param/video/raw.h | 99 ++++++---------- 4 files changed, 158 insertions(+), 249 deletions(-) diff --git a/spa/include/spa/param/video/chroma.h b/spa/include/spa/param/video/chroma.h index 36268d2c0..7e73c6d90 100644 --- a/spa/include/spa/param/video/chroma.h +++ b/spa/include/spa/param/video/chroma.h @@ -30,26 +30,21 @@ extern "C" { #endif /** Various Chroma settings. - * @SPA_VIDEO_CHROMA_SITE_UNKNOWN: unknown cositing - * @SPA_VIDEO_CHROMA_SITE_NONE: no cositing - * @SPA_VIDEO_CHROMA_SITE_H_COSITED: chroma is horizontally cosited - * @SPA_VIDEO_CHROMA_SITE_V_COSITED: chroma is vertically cosited - * @SPA_VIDEO_CHROMA_SITE_ALT_LINE: chroma samples are sited on alternate lines - * @SPA_VIDEO_CHROMA_SITE_COSITED: chroma samples cosited with luma samples - * @SPA_VIDEO_CHROMA_SITE_JPEG: jpeg style cositing, also for mpeg1 and mjpeg - * @SPA_VIDEO_CHROMA_SITE_MPEG2: mpeg2 style cositing - * @SPA_VIDEO_CHROMA_SITE_DV: DV style cositing */ enum spa_video_chroma_site { - SPA_VIDEO_CHROMA_SITE_UNKNOWN = 0, - SPA_VIDEO_CHROMA_SITE_NONE = (1 << 0), - SPA_VIDEO_CHROMA_SITE_H_COSITED = (1 << 1), - SPA_VIDEO_CHROMA_SITE_V_COSITED = (1 << 2), - SPA_VIDEO_CHROMA_SITE_ALT_LINE = (1 << 3), + SPA_VIDEO_CHROMA_SITE_UNKNOWN = 0, /**< unknown cositing */ + SPA_VIDEO_CHROMA_SITE_NONE = (1 << 0), /**< no cositing */ + SPA_VIDEO_CHROMA_SITE_H_COSITED = (1 << 1), /**< chroma is horizontally cosited */ + SPA_VIDEO_CHROMA_SITE_V_COSITED = (1 << 2), /**< chroma is vertically cosited */ + SPA_VIDEO_CHROMA_SITE_ALT_LINE = (1 << 3), /**< chroma samples are sited on alternate lines */ /* some common chroma cositing */ + /** chroma samples cosited with luma samples */ SPA_VIDEO_CHROMA_SITE_COSITED = (SPA_VIDEO_CHROMA_SITE_H_COSITED | SPA_VIDEO_CHROMA_SITE_V_COSITED), + /** jpeg style cositing, also for mpeg1 and mjpeg */ SPA_VIDEO_CHROMA_SITE_JPEG = (SPA_VIDEO_CHROMA_SITE_NONE), + /** mpeg2 style cositing */ SPA_VIDEO_CHROMA_SITE_MPEG2 = (SPA_VIDEO_CHROMA_SITE_H_COSITED), + /**< DV style cositing */ SPA_VIDEO_CHROMA_SITE_DV = (SPA_VIDEO_CHROMA_SITE_COSITED | SPA_VIDEO_CHROMA_SITE_ALT_LINE), }; diff --git a/spa/include/spa/param/video/color.h b/spa/include/spa/param/video/color.h index 7de8c3672..3fe9f1834 100644 --- a/spa/include/spa/param/video/color.h +++ b/spa/include/spa/param/video/color.h @@ -30,129 +30,83 @@ extern "C" { #endif /** - * spa_video_color_range: - * @SPA_VIDEO_COLOR_RANGE_UNKNOWN: unknown range - * @SPA_VIDEO_COLOR_RANGE_0_255: [0..255] for 8 bit components - * @SPA_VIDEO_COLOR_RANGE_16_235: [16..235] for 8 bit components. Chroma has - * [16..240] range. - * * Possible color range values. These constants are defined for 8 bit color * values and can be scaled for other bit depths. */ enum spa_video_color_range { - SPA_VIDEO_COLOR_RANGE_UNKNOWN = 0, - SPA_VIDEO_COLOR_RANGE_0_255, - SPA_VIDEO_COLOR_RANGE_16_235 + SPA_VIDEO_COLOR_RANGE_UNKNOWN = 0, /**< unknown range */ + SPA_VIDEO_COLOR_RANGE_0_255, /**< [0..255] for 8 bit components */ + SPA_VIDEO_COLOR_RANGE_16_235 /**< [16..235] for 8 bit components. Chroma has + [16..240] range. */ }; /** - * spa_video_color_matrix: - * @SPA_VIDEO_COLOR_MATRIX_UNKNOWN: unknown matrix - * @SPA_VIDEO_COLOR_MATRIX_RGB: identity matrix - * @SPA_VIDEO_COLOR_MATRIX_FCC: FCC color matrix - * @SPA_VIDEO_COLOR_MATRIX_BT709: ITU-R BT.709 color matrix - * @SPA_VIDEO_COLOR_MATRIX_BT601: ITU-R BT.601 color matrix - * @SPA_VIDEO_COLOR_MATRIX_SMPTE240M: SMPTE 240M color matrix - * @SPA_VIDEO_COLOR_MATRIX_BT2020: ITU-R BT.2020 color matrix. Since: 1.6. - * * The color matrix is used to convert between Y'PbPr and * non-linear RGB (R'G'B') */ enum spa_video_color_matrix { - SPA_VIDEO_COLOR_MATRIX_UNKNOWN = 0, - SPA_VIDEO_COLOR_MATRIX_RGB, - SPA_VIDEO_COLOR_MATRIX_FCC, - SPA_VIDEO_COLOR_MATRIX_BT709, - SPA_VIDEO_COLOR_MATRIX_BT601, - SPA_VIDEO_COLOR_MATRIX_SMPTE240M, - SPA_VIDEO_COLOR_MATRIX_BT2020 + SPA_VIDEO_COLOR_MATRIX_UNKNOWN = 0, /**< unknown matrix */ + SPA_VIDEO_COLOR_MATRIX_RGB, /**< identity matrix */ + SPA_VIDEO_COLOR_MATRIX_FCC, /**< FCC color matrix */ + SPA_VIDEO_COLOR_MATRIX_BT709, /**< ITU BT.709 color matrix */ + SPA_VIDEO_COLOR_MATRIX_BT601, /**< ITU BT.601 color matrix */ + SPA_VIDEO_COLOR_MATRIX_SMPTE240M, /**< SMTPE 240M color matrix */ + SPA_VIDEO_COLOR_MATRIX_BT2020, /**< ITU-R BT.2020 color matrix. since 1.6. */ }; /** - * spa_video_transfer_function: - * @SPA_VIDEO_TRANSFER_UNKNOWN: unknown transfer function - * @SPA_VIDEO_TRANSFER_GAMMA10: linear RGB, gamma 1.0 curve - * @SPA_VIDEO_TRANSFER_GAMMA18: Gamma 1.8 curve - * @SPA_VIDEO_TRANSFER_GAMMA20: Gamma 2.0 curve - * @SPA_VIDEO_TRANSFER_GAMMA22: Gamma 2.2 curve - * @SPA_VIDEO_TRANSFER_BT709: Gamma 2.2 curve with a linear segment in the lower - * range - * @SPA_VIDEO_TRANSFER_SMPTE240M: Gamma 2.2 curve with a linear segment in the - * lower range - * @SPA_VIDEO_TRANSFER_SRGB: Gamma 2.4 curve with a linear segment in the lower - * range - * @SPA_VIDEO_TRANSFER_GAMMA28: Gamma 2.8 curve - * @SPA_VIDEO_TRANSFER_LOG100: Logarithmic transfer characteristic - * 100:1 range - * @SPA_VIDEO_TRANSFER_LOG316: Logarithmic transfer characteristic - * 316.22777:1 range - * @SPA_VIDEO_TRANSFER_BT2020_12: Gamma 2.2 curve with a linear segment in the lower - * range. Used for BT.2020 with 12 bits per - * component. Since: 1.6. - * @SPA_VIDEO_TRANSFER_ADOBERGB: Gamma 2.19921875. Since: 1.8 - * * The video transfer function defines the formula for converting between * non-linear RGB (R'G'B') and linear RGB */ enum spa_video_transfer_function { - SPA_VIDEO_TRANSFER_UNKNOWN = 0, - SPA_VIDEO_TRANSFER_GAMMA10, - SPA_VIDEO_TRANSFER_GAMMA18, - SPA_VIDEO_TRANSFER_GAMMA20, - SPA_VIDEO_TRANSFER_GAMMA22, - SPA_VIDEO_TRANSFER_BT709, - SPA_VIDEO_TRANSFER_SMPTE240M, - SPA_VIDEO_TRANSFER_SRGB, - SPA_VIDEO_TRANSFER_GAMMA28, - SPA_VIDEO_TRANSFER_LOG100, - SPA_VIDEO_TRANSFER_LOG316, - SPA_VIDEO_TRANSFER_BT2020_12, - SPA_VIDEO_TRANSFER_ADOBERGB + SPA_VIDEO_TRANSFER_UNKNOWN = 0, /**< unknown transfer function */ + SPA_VIDEO_TRANSFER_GAMMA10, /**< linear RGB, gamma 1.0 curve */ + SPA_VIDEO_TRANSFER_GAMMA18, /**< Gamma 1.8 curve */ + SPA_VIDEO_TRANSFER_GAMMA20, /**< Gamma 2.0 curve */ + SPA_VIDEO_TRANSFER_GAMMA22, /**< Gamma 2.2 curve */ + SPA_VIDEO_TRANSFER_BT709, /**< Gamma 2.2 curve with a linear segment in the lower range */ + SPA_VIDEO_TRANSFER_SMPTE240M, /**< Gamma 2.2 curve with a linear segment in the lower range */ + SPA_VIDEO_TRANSFER_SRGB, /**< Gamma 2.4 curve with a linear segment in the lower range */ + SPA_VIDEO_TRANSFER_GAMMA28, /**< Gamma 2.8 curve */ + SPA_VIDEO_TRANSFER_LOG100, /**< Logarithmic transfer characteristic 100:1 range */ + SPA_VIDEO_TRANSFER_LOG316, /**< Logarithmic transfer characteristic 316.22777:1 range */ + SPA_VIDEO_TRANSFER_BT2020_12, /**< Gamma 2.2 curve with a linear segment in the lower + * range. Used for BT.2020 with 12 bits per + * component. \since 1.6. */ + SPA_VIDEO_TRANSFER_ADOBERGB, /**< Gamma 2.19921875. \since 1.8 */ }; /** - * spa_video_color_primaries: - * @SPA_VIDEO_COLOR_PRIMARIES_UNKNOWN: unknown color primaries - * @SPA_VIDEO_COLOR_PRIMARIES_BT709: BT709 primaries - * @SPA_VIDEO_COLOR_PRIMARIES_BT470M: BT470M primaries - * @SPA_VIDEO_COLOR_PRIMARIES_BT470BG: BT470BG primaries - * @SPA_VIDEO_COLOR_PRIMARIES_SMPTE170M: SMPTE170M primaries - * @SPA_VIDEO_COLOR_PRIMARIES_SMPTE240M: SMPTE240M primaries - * @SPA_VIDEO_COLOR_PRIMARIES_FILM: Generic film - * @SPA_VIDEO_COLOR_PRIMARIES_BT2020: BT2020 primaries. Since: 1.6. - * @SPA_VIDEO_COLOR_PRIMARIES_ADOBERGB: Adobe RGB primaries. Since: 1.8 - * * The color primaries define the how to transform linear RGB values to and from * the CIE XYZ colorspace. */ enum spa_video_color_primaries { - SPA_VIDEO_COLOR_PRIMARIES_UNKNOWN = 0, - SPA_VIDEO_COLOR_PRIMARIES_BT709, - SPA_VIDEO_COLOR_PRIMARIES_BT470M, - SPA_VIDEO_COLOR_PRIMARIES_BT470BG, - SPA_VIDEO_COLOR_PRIMARIES_SMPTE170M, - SPA_VIDEO_COLOR_PRIMARIES_SMPTE240M, - SPA_VIDEO_COLOR_PRIMARIES_FILM, - SPA_VIDEO_COLOR_PRIMARIES_BT2020, - SPA_VIDEO_COLOR_PRIMARIES_ADOBERGB + SPA_VIDEO_COLOR_PRIMARIES_UNKNOWN = 0, /**< unknown color primaries */ + SPA_VIDEO_COLOR_PRIMARIES_BT709, /**< BT709 primaries */ + SPA_VIDEO_COLOR_PRIMARIES_BT470M, /**< BT470M primaries */ + SPA_VIDEO_COLOR_PRIMARIES_BT470BG, /**< BT470BG primaries */ + SPA_VIDEO_COLOR_PRIMARIES_SMPTE170M, /**< SMPTE170M primaries */ + SPA_VIDEO_COLOR_PRIMARIES_SMPTE240M, /**< SMPTE240M primaries */ + SPA_VIDEO_COLOR_PRIMARIES_FILM, /**< Generic film */ + SPA_VIDEO_COLOR_PRIMARIES_BT2020, /**< BT2020 primaries. \since 1.6. */ + SPA_VIDEO_COLOR_PRIMARIES_ADOBERGB, /**< Adobe RGB primaries. \since 1.8 */ }; /** * spa_video_colorimetry: - * @range: the color range. This is the valid range for the samples. - * It is used to convert the samples to Y'PbPr values. - * @matrix: the color matrix. Used to convert between Y'PbPr and - * non-linear RGB (R'G'B') - * @transfer: the transfer function. used to convert between R'G'B' and RGB - * @primaries: color primaries. used to convert between R'G'B' and CIE XYZ * * Structure describing the color info. */ struct spa_video_colorimetry { - enum spa_video_color_range range; - enum spa_video_color_matrix matrix; - enum spa_video_transfer_function transfer; - enum spa_video_color_primaries primaries; + enum spa_video_color_range range; /**< The color range. This is the valid range for the + * samples. It is used to convert the samples to Y'PbPr + * values. */ + enum spa_video_color_matrix matrix; /**< the color matrix. Used to convert between Y'PbPr and + * non-linear RGB (R'G'B') */ + enum spa_video_transfer_function transfer; /**< The transfer function. Used to convert between + * R'G'B' and RGB */ + enum spa_video_color_primaries primaries; /**< Color primaries. Used to convert between R'G'B' + * and CIE XYZ */ }; #ifdef __cplusplus diff --git a/spa/include/spa/param/video/multiview.h b/spa/include/spa/param/video/multiview.h index e797271ac..ef2bbe671 100644 --- a/spa/include/spa/param/video/multiview.h +++ b/spa/include/spa/param/video/multiview.h @@ -30,106 +30,91 @@ extern "C" { #endif /** - * spa_video_multiview_mode: - * @SPA_VIDEO_MULTIVIEW_MODE_NONE: A special value indicating - * no multiview information. Used in spa_video_info and other places to - * indicate that no specific multiview handling has been requested or - * provided. This value is never carried on caps. - * @SPA_VIDEO_MULTIVIEW_MODE_MONO: All frames are monoscopic. - * @SPA_VIDEO_MULTIVIEW_MODE_LEFT: All frames represent a left-eye view. - * @SPA_VIDEO_MULTIVIEW_MODE_RIGHT: All frames represent a right-eye view. - * @SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE: Left and right eye views are - * provided in the left and right half of the frame respectively. - * @SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX: Left and right eye - * views are provided in the left and right half of the frame, but - * have been sampled using quincunx method, with half-pixel offset - * between the 2 views. - * @SPA_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED: Alternating vertical - * columns of pixels represent the left and right eye view respectively. - * @SPA_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED: Alternating horizontal - * rows of pixels represent the left and right eye view respectively. - * @SPA_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM: The top half of the frame - * contains the left eye, and the bottom half the right eye. - * @SPA_VIDEO_MULTIVIEW_MODE_CHECKERBOARD: Pixels are arranged with - * alternating pixels representing left and right eye views in a - * checkerboard fashion. - * @SPA_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME: Left and right eye views - * are provided in separate frames alternately. - * @SPA_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME: Multiple - * independent views are provided in separate frames in sequence. - * This method only applies to raw video buffers at the moment. - * Specific view identification is via the #spa_video_multiview_meta - * on raw video buffers. - * @SPA_VIDEO_MULTIVIEW_MODE_SEPARATED: Multiple views are - * provided as separate #spa_data framebuffers attached to each - * #spa_buffer, described by the #spa_video_multiview_meta - * * All possible stereoscopic 3D and multiview representations. - * In conjunction with #soa_video_multiview_flags, describes how + * In conjunction with \ref spa_video_multiview_flags, describes how * multiview content is being transported in the stream. */ enum spa_video_multiview_mode { + /** A special value indicating no multiview information. Used in spa_video_info and other + * places to indicate that no specific multiview handling has been requested or provided. + * This value is never carried on caps. */ SPA_VIDEO_MULTIVIEW_MODE_NONE = -1, - SPA_VIDEO_MULTIVIEW_MODE_MONO = 0, + SPA_VIDEO_MULTIVIEW_MODE_MONO = 0, /**< All frames are monoscopic */ /* Single view modes */ - SPA_VIDEO_MULTIVIEW_MODE_LEFT, - SPA_VIDEO_MULTIVIEW_MODE_RIGHT, + SPA_VIDEO_MULTIVIEW_MODE_LEFT, /**< All frames represent a left-eye view */ + SPA_VIDEO_MULTIVIEW_MODE_RIGHT, /**< All frames represent a right-eye view */ /* Stereo view modes */ - SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE, - SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX, - SPA_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED, - SPA_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED, - SPA_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM, - SPA_VIDEO_MULTIVIEW_MODE_CHECKERBOARD, + SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE, /**< Left and right eye views are provided + * in the left and right half of the frame + * respectively. */ + SPA_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX, /**< Left and right eye views are provided + * in the left and right half of the + * frame, but have been sampled using + * quincunx method, with half-pixel offset + * between the 2 views. */ + SPA_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED, /**< Alternating vertical columns of pixels + * represent the left and right eye view + * respectively. */ + SPA_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED, /**< Alternating horizontal rows of pixels + * represent the left and right eye view + * respectively. */ + SPA_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM, /**< The top half of the frame contains the + * left eye, and the bottom half the right + * eye. */ + SPA_VIDEO_MULTIVIEW_MODE_CHECKERBOARD, /**< Pixels are arranged with alternating + * pixels representing left and right eye + * views in a checkerboard fashion. */ /* Padding for new frame packing modes */ - SPA_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME = 32, + SPA_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME = 32, /**< Left and right eye views are provided + * in separate frames alternately. */ /* Multiview mode(s) */ - SPA_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME, - SPA_VIDEO_MULTIVIEW_MODE_SEPARATED - /* future expansion for annotated modes */ + SPA_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME, /**< Multipleindependent views are + * provided in separate frames in + * sequence. This method only applies to + * raw video buffers at the moment. + * Specific view identification is via + * \ref spa_video_multiview_meta on raw + * video buffers. */ + SPA_VIDEO_MULTIVIEW_MODE_SEPARATED, /**< Multiple views are provided as separate + * \ref spa_data framebuffers attached + * to each \ref spa_buffer, described + * by the \ref spa_video_multiview_meta */ + /* future expansion for annotated modes */ }; /** - * spa_video_multiview_flags: - * @SPA_VIDEO_MULTIVIEW_FLAGS_NONE: No flags - * @SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST: For stereo streams, the - * normal arrangement of left and right views is reversed. - * @SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED: The left view is vertically - * mirrored. - * @SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED: The left view is horizontally - * mirrored. - * @SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED: The right view is - * vertically mirrored. - * @SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED: The right view is - * horizontally mirrored. - * @SPA_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT: For frame-packed - * multiview modes, indicates that the individual - * views have been encoded with half the true width or height - * and should be scaled back up for display. This flag - * is used for overriding input layout interpretation - * by adjusting pixel-aspect-ratio. - * For side-by-side, column interleaved or checkerboard packings, the - * pixel width will be doubled. For row interleaved and top-bottom - * encodings, pixel height will be doubled. - * @SPA_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO: The video stream contains both - * mono and multiview portions, signalled on each buffer by the - * absence or presence of the @SPA_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW - * buffer flag. - * * spa_video_multiview_flags are used to indicate extra properties of a * stereo/multiview stream beyond the frame layout and buffer mapping - * that is conveyed in the #spa_video_multiview_mode. + * that is conveyed in the \ref spa_video_multiview_mode. */ enum spa_video_multiview_flags { - SPA_VIDEO_MULTIVIEW_FLAGS_NONE = 0, - SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST = (1 << 0), - SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED = (1 << 1), - SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED = (1 << 2), - SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED = (1 << 3), - SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED = (1 << 4), - SPA_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT = (1 << 14), - SPA_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO = (1 << 15) + SPA_VIDEO_MULTIVIEW_FLAGS_NONE = 0, /**< No flags */ + SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST = (1 << 0), /**< For stereo streams, the normal arrangement + * of left and right views is reversed */ + SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED = (1 << 1), /**< The left view is vertically mirrored */ + SPA_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED = (1 << 2), /**< The left view is horizontally mirrored */ + SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED = (1 << 3), /**< The right view is vertically mirrored */ + SPA_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED = (1 << 4), /**< The right view is horizontally mirrored */ + SPA_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT = (1 << 14), /**< For frame-packed multiview + * modes, indicates that the individual + * views have been encoded with half the true + * width or height and should be scaled back + * up for display. This flag is used for + * overriding input layout interpretation + * by adjusting pixel-aspect-ratio. + * For side-by-side, column interleaved or + * checkerboard packings, the + * pixel width will be doubled. + * For row interleaved and + * top-bottom encodings, pixel height will + * be doubled */ + SPA_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO = (1 << 15), /**< The video stream contains both + * mono and multiview portions, + * signalled on each buffer by the + * absence or presence of the + * \ref SPA_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW + * buffer flag. */ }; diff --git a/spa/include/spa/param/video/raw.h b/spa/include/spa/param/video/raw.h index eab65b8ec..833f9a330 100644 --- a/spa/include/spa/param/video/raw.h +++ b/spa/include/spa/param/video/raw.h @@ -126,83 +126,58 @@ enum spa_video_format { }; /** - * spa_video_flags: - * @SPA_VIDEO_FLAG_NONE: no flags - * @SPA_VIDEO_FLAG_VARIABLE_FPS: a variable fps is selected, fps_n and fps_d - * denote the maximum fps of the video - * @SPA_VIDEO_FLAG_PREMULTIPLIED_ALPHA: Each color has been scaled by the alpha - * value. - * * Extra video flags */ enum spa_video_flags { - SPA_VIDEO_FLAG_NONE = 0, - SPA_VIDEO_FLAG_VARIABLE_FPS = (1 << 0), - SPA_VIDEO_FLAG_PREMULTIPLIED_ALPHA = (1 << 1) + SPA_VIDEO_FLAG_NONE = 0, /**< no flags */ + SPA_VIDEO_FLAG_VARIABLE_FPS = (1 << 0), /**< a variable fps is selected, fps_n and fps_d + * denote the maximum fps of the video */ + SPA_VIDEO_FLAG_PREMULTIPLIED_ALPHA = (1 << 1), /**< Each color has been scaled by the alpha value. */ }; /** - * spa_video_interlace_mode: - * @SPA_VIDEO_INTERLACE_MODE_PROGRESSIVE: all frames are progressive - * @SPA_VIDEO_INTERLACE_MODE_INTERLEAVED: 2 fields are interleaved in one video - * frame. Extra buffer flags describe the field order. - * @SPA_VIDEO_INTERLACE_MODE_MIXED: frames contains both interlaced and - * progressive video, the buffer flags describe the frame and fields. - * @SPA_VIDEO_INTERLACE_MODE_FIELDS: 2 fields are stored in one buffer, use the - * frame ID to get access to the required field. For multiview (the - * 'views' property > 1) the fields of view N can be found at frame ID - * (N * 2) and (N * 2) + 1. - * Each field has only half the amount of lines as noted in the - * height property. This mode requires multiple spa_data - * to describe the fields. - * * The possible values of the #spa_video_interlace_mode describing the interlace * mode of the stream. */ enum spa_video_interlace_mode { - SPA_VIDEO_INTERLACE_MODE_PROGRESSIVE = 0, - SPA_VIDEO_INTERLACE_MODE_INTERLEAVED, - SPA_VIDEO_INTERLACE_MODE_MIXED, - SPA_VIDEO_INTERLACE_MODE_FIELDS + SPA_VIDEO_INTERLACE_MODE_PROGRESSIVE = 0, /**< all frames are progressive */ + SPA_VIDEO_INTERLACE_MODE_INTERLEAVED, /**< 2 fields are interleaved in one video frame. + * Extra buffer flags describe the field order. */ + SPA_VIDEO_INTERLACE_MODE_MIXED, /**< frames contains both interlaced and progressive + * video, the buffer flags describe the frame and + * fields. */ + SPA_VIDEO_INTERLACE_MODE_FIELDS, /**< 2 fields are stored in one buffer, use the + * frame ID to get access to the required + * field. For multiview (the 'views' + * property > 1) the fields of view N can + * be found at frame ID (N * 2) and (N * + * 2) + 1. Each field has only half the + * amount of lines as noted in the height + * property. This mode requires multiple + * spa_data to describe the fields. */ }; /** - * spa_video_info_raw: - * @format: the format - * @modifier: format modifier - * @size: the frame size of the video - * @framerate: the framerate of the video 0/1 means variable rate - * @max_framerate: the maximum framerate of the video. This is only valid when - * @framerate is 0/1 - * @views: the number of views in this video - * @interlace_mode: the interlace mode - * @pixel_aspect_ratio: The pixel aspect ratio - * @multiview_mode: multiview mode - * @multiview_flags: multiview flags - * @chroma_site: the chroma siting - * @color_range: the color range. This is the valid range for the samples. - * It is used to convert the samples to Y'PbPr values. - * @color_matrix: the color matrix. Used to convert between Y'PbPr and - * non-linear RGB (R'G'B') - * @transfer_function: the transfer function. used to convert between R'G'B' and RGB - * @color_primaries: color primaries. used to convert between R'G'B' and CIE XYZ */ struct spa_video_info_raw { - enum spa_video_format format; - int64_t modifier; - struct spa_rectangle size; - struct spa_fraction framerate; - struct spa_fraction max_framerate; - uint32_t views; - enum spa_video_interlace_mode interlace_mode; - struct spa_fraction pixel_aspect_ratio; - enum spa_video_multiview_mode multiview_mode; - enum spa_video_multiview_flags multiview_flags; - enum spa_video_chroma_site chroma_site; - enum spa_video_color_range color_range; - enum spa_video_color_matrix color_matrix; - enum spa_video_transfer_function transfer_function; - enum spa_video_color_primaries color_primaries; + enum spa_video_format format; /**< the format */ + int64_t modifier; /**< format modifier */ + struct spa_rectangle size; /**< the frame size of the video */ + struct spa_fraction framerate; /**< the framerate of the video, 0/1 means variable rate */ + struct spa_fraction max_framerate; /**< the maximum framerate of the video. This is only valid when + \ref framerate is 0/1 */ + uint32_t views; /**< the number of views in this video */ + enum spa_video_interlace_mode interlace_mode; /**< the interlace mode */ + struct spa_fraction pixel_aspect_ratio; /**< the pixel aspect ratio */ + enum spa_video_multiview_mode multiview_mode; /**< multiview mode */ + enum spa_video_multiview_flags multiview_flags; /**< multiview flags */ + enum spa_video_chroma_site chroma_site; /**< the chroma siting */ + enum spa_video_color_range color_range; /**< the color range. This is the valid range for the samples. + * It is used to convert the samples to Y'PbPr values. */ + enum spa_video_color_matrix color_matrix; /**< the color matrix. Used to convert between Y'PbPr and + * non-linear RGB (R'G'B') */ + enum spa_video_transfer_function transfer_function; /**< the transfer function. used to convert between R'G'B' and RGB */ + enum spa_video_color_primaries color_primaries; /**< color primaries. used to convert between R'G'B' and CIE XYZ */ }; #define SPA_VIDEO_INFO_RAW_INIT(...) (struct spa_video_info_raw) { __VA_ARGS__ }