{Audio,Video}CapsBuilder: add for_encoding constructor

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/merge_requests/1222>

gstreamer-audio/src/caps.rs

@@ -11,7 +11,19 @@ pub struct AudioCapsBuilder<T> {
 }
 
 impl AudioCapsBuilder<gst::caps::NoFeature> {
+    // rustdoc-stripper-ignore-next
+    /// Constructs an `AudioCapsBuilder` for the "audio/x-raw" encoding.
+    ///
+    /// If left unchanged, the resulting `Caps` will be initialized with:
+    /// - "audio/x-raw" encoding.
+    /// - maximum rate range.
+    /// - maximum channels range.
+    /// - both interleaved and non-interleaved layouts.
+    /// - all available formats.
+    ///
+    /// Use [`AudioCapsBuilder::for_encoding`] to specify another encoding.
     pub fn new() -> Self {
+        assert_initialized_main_thread!();
         let builder = Caps::builder(glib::gstr!("audio/x-raw"));
         let builder = AudioCapsBuilder { builder };
         builder
@@ -21,10 +33,34 @@ impl AudioCapsBuilder<gst::caps::NoFeature> {
             .format_list(AudioFormat::iter_raw())
     }
 
+    // rustdoc-stripper-ignore-next
+    /// Constructs an `AudioCapsBuilder` for the "audio/x-raw" encoding
+    /// with interleaved layout.
+    ///
+    /// If left unchanged, the resulting `Caps` will be initialized with:
+    /// - "audio/x-raw" encoding.
+    /// - maximum rate range.
+    /// - maximum channels range.
+    /// - interleaved layout.
+    /// - all available formats.
+    ///
+    /// Use [`AudioCapsBuilder::for_encoding`] to specify another encoding.
     pub fn new_interleaved() -> Self {
         AudioCapsBuilder::new().layout(AudioLayout::Interleaved)
     }
 
+    // rustdoc-stripper-ignore-next
+    /// Constructs an `AudioCapsBuilder` for the specified encoding.
+    ///
+    /// The resulting `Caps` will use the `encoding` argument as name
+    /// and will not contain any additional fields unless explicitly added.
+    pub fn for_encoding(encoding: impl IntoGStr) -> Self {
+        assert_initialized_main_thread!();
+        AudioCapsBuilder {
+            builder: Caps::builder(encoding),
+        }
+    }
+
     pub fn any_features(self) -> AudioCapsBuilder<gst::caps::HasFeatures> {
         AudioCapsBuilder {
             builder: self.builder.any_features(),
@@ -180,3 +216,22 @@ fn layout_str(layout: AudioLayout) -> &'static glib::GStr {
         crate::AudioLayout::__Unknown(_) => glib::gstr!("unknown"),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::AudioCapsBuilder;
+
+    #[test]
+    fn default_encoding() {
+        gst::init().unwrap();
+        let caps = AudioCapsBuilder::new().build();
+        assert_eq!(caps.structure(0).unwrap().name(), "audio/x-raw");
+    }
+
+    #[test]
+    fn explicit_encoding() {
+        gst::init().unwrap();
+        let caps = AudioCapsBuilder::for_encoding("audio/mpeg").build();
+        assert_eq!(caps.structure(0).unwrap().name(), "audio/mpeg");
+    }
+}

gstreamer-video/src/caps.rs

@@ -10,7 +10,18 @@ pub struct VideoCapsBuilder<T> {
 }
 
 impl VideoCapsBuilder<gst::caps::NoFeature> {
+    // rustdoc-stripper-ignore-next
+    /// Constructs an `VideoCapsBuilder` for the "video/x-raw" encoding.
+    ///
+    /// If left unchanged, the resulting `Caps` will be initialized with:
+    /// - "video/x-raw" encoding.
+    /// - all available formats.
+    /// - maximum width range.
+    /// - maximum height range.
+    ///
+    /// Use [`VideoCapsBuilder::for_encoding`] to specify another encoding.
     pub fn new() -> Self {
+        assert_initialized_main_thread!();
         let builder = Caps::builder(glib::gstr!("video/x-raw"));
         let builder = VideoCapsBuilder { builder };
         builder
@@ -20,6 +31,18 @@ impl VideoCapsBuilder<gst::caps::NoFeature> {
             .framerate_range(..)
     }
 
+    // rustdoc-stripper-ignore-next
+    /// Constructs an `VideoCapsBuilder` for the specified encoding.
+    ///
+    /// The resulting `Caps` will use the `encoding` argument as name
+    /// and will not contain any additional fields unless explicitly added.
+    pub fn for_encoding(encoding: impl IntoGStr) -> Self {
+        assert_initialized_main_thread!();
+        VideoCapsBuilder {
+            builder: Caps::builder(encoding),
+        }
+    }
+
     pub fn any_features(self) -> VideoCapsBuilder<gst::caps::HasFeatures> {
         VideoCapsBuilder {
             builder: self.builder.any_features(),
@@ -283,6 +306,24 @@ fn next_fraction(fraction: gst::Fraction) -> gst::Fraction {
     gst::Fraction::new(new_num, new_den)
 }
 
+#[cfg(test)]
+mod tests {
+    use super::{next_fraction, previous_fraction, VideoCapsBuilder};
+
+    #[test]
+    fn default_encoding() {
+        gst::init().unwrap();
+        let caps = VideoCapsBuilder::new().build();
+        assert_eq!(caps.structure(0).unwrap().name(), "video/x-raw");
+    }
+
+    #[test]
+    fn explicit_encoding() {
+        gst::init().unwrap();
+        let caps = VideoCapsBuilder::for_encoding("video/mpeg").build();
+        assert_eq!(caps.structure(0).unwrap().name(), "video/mpeg");
+    }
+
     #[test]
     fn test_0_1_fraction() {
         gst::init().unwrap();
@@ -321,3 +362,4 @@ fn test_1_25() {
         assert_eq!(prev.numer(), 85899345);
         assert_eq!(prev.denom(), 2147483626);
     }
+}