Add CHANGELOG.md/README.md to pbutils

2018-03-20 13:02:32 +02:00 · 2018-03-20 13:02:32 +02:00 · 3784b0a97d
commit 3784b0a97d
parent 03055f4e84
2 changed files with 423 additions and 0 deletions
--- a/gstreamer-pbutils/CHANGELOG.md
+++ b/gstreamer-pbutils/CHANGELOG.md
@ -0,0 +1,253 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html),
+specifically the [variant used by Rust](http://doc.crates.io/manifest.html#the-version-field).
+
+## [0.11.0] - 2018-03-20
+### Changed
+- Updated everything to GStreamer 1.14.0
+- Event, Message and Query types were refactored to improve usability.
+  Especially newly constructed queries allow to directly use the type-specific
+  functions to be used without first creating a view
+- VideoFrameRef::copy_to_ref() and ::copy_plane_to_ref() are gone now and the
+  original functions work with refs instead of full frames
+- PadProbeId and NotifyIds are not Copy/Clone anymore and are taken by value
+- GstPlayer has GstObject as parent class now
+
+### Added
+- GstPbutils, GstSdp, GstRtsp and GstRtspServer bindings
+- GstPromise, GstAudioStreamAlign and various other 1.14 API
+- GstVideoFilter and GstBufferPool bindings
+- Element::call_async()
+- Debug impl For Toc and TocEntry
+- Various new examples (RTP FEC, RTSP server, tag usage, ...)
+
+### Fixed
+- Memory leak in gst_video::convert_sample_async()
+
+## [0.10.2] - 2018-02-18
+### Fixed
+- Fix building of messages with custom fields for types that don't have a
+  GstStructure
+
+### Added
+- VideoFrameRef::copy_to_ref() and ::copy_plane_to_ref(), which work with
+  VideoFrameRefs instead of full VideoFrames
+- Getters for the BaseSrc/Sink/Transform configured segment
+- Document the gstreamer-player-1.0 dependency in the README.md
+
+## [0.10.1] - 2018-01-03
+### Fixed
+- Don't require &mut self for TagSetterExtManual::add()
+
+### Added
+- A TagSetter example application
+- Bindings for gst_video::convert_sample() and ::convert_sample_async()
+- Bindings for gst_video::VideoRectangle
+- Debug impl for Sample and ::with_buffer_list() constructor
+- A borrowing version of VideoFrame: VideoFrameRef
+- Bindings for GstVideoFilter
+
+### Changed
+- Deprecated Sample::get_info() in favour of ::get_structure()
+- Player has gst::Object as another parent class now
+
+## [0.10.0] - 2017-12-22
+### Fixed
+- Various clippy warnings
+- Memory leak of the tag list in Toc::merge_tags()
+- Property getters use Values of the correct type
+- Event::get_structure(), Message::get_structure() and
+  Query::get_structure() can return None for the structure
+- Various other nullability fixes all over the API, changing functions to
+  accept Option<> or returning Option<>, or only plain types
+- Functions taking paths/filenames now actually take Paths instead of &strs
+- Element::remove_pad() is not giving away a new reference to the pad
+  anymore, which caused a memory leak of all pads ever removed
+- Precision handling in ClockTime's Display impl
+- Video/AudioInfo are only Send, not Sync
+
+### Added
+- Various enums now also derive useful traits like Copy, Clone and Hash in
+  addition to PartialEq, Eq and Debug
+- TagList::merge() and insert() for combining tag lists
+- EventType gained many useful functions to work with event types and
+  a PartialOrd impl to check expected event order of event types where it matters
+- MessageRef/EventRef/QueryRef implement ToOwned
+- Bindings for Registry and PluginFeature
+- Event::set_running_time_offset() for adjusting the offset while events
+  pass through the pipeline
+- Event/Message GroupIds and Seqnums now have a newtype wrapper around u32
+  instead of the plain value, making usage of them slightly more typesafe.
+  Also add an "invalid" value for both, as exists in latest GStreamer now.
+- FormattedValue, GenericFormattedValue and related types were
+  implemented now, which allows more convenient and type-safe usage of
+  formatted values (time, bytes, etc)
+- Bindings for force-keyunit and still-frame events were added
+- MappedBuffer/BufferMap now implement various other useful traits, including
+  AsRef<[u8]>, AsMut, Deref, DerefMut, Debug, PartialEq and Eq
+- Add VideoMultiviewFramePacking enum, and use it in Player
+- Bindings for the GStreamer Net library, including PTP/NTP/network client
+  clocks and the GStreamer NetClock provider for network synchronization of
+  pipelines
+- IteratorError implements std::error:Error
+- Plugin::add_dependency() and ::add_dependency_simple() was added
+- Rank and TypeFindProbability implement PartialOrd/Ord now
+- Bindings for TypeFind, TypeFindFactory and the typefind helpers
+- StreamCollection::iter() for iterating over all contained streams
+- ErrorMessage type that can be used e.g. in a Result for passing an error
+  message from somewhere to upper layers to then be posted on an element the
+  same way gst_element_error!() would've done
+
+### Changed
+- Sample::new(), TagList::add(), Structure::set() and similar
+  functions take the values (ToSendValue impls) by reference instead of value.
+  They were not consumed by the function before.
+- The Debug impls of various types, including Event/Buffer/Message/Query/Structure
+  were improved to print all the fields, similar to what GST_PTR_FORMAT would
+  do in C
+- Switched to lazy_static 1.0
+- Gap event and Duration tag are using ClockTimes now, as well as various
+  Player signals
+- Segment is now based on a generic type FormattedSegment that can
+  take any format (time, bytes, etc) or a GenericFormattedValue for more
+  type-safety and convenience. Also functions for "casting" between a generic
+  segment and a segment with a specific format exist on this now
+- AppSrc and AppSink now have a builder for the callbacks, making it
+  unnecessary to always provide all callbacks even if only one is actually
+  needed
+- Various functions that returned bool for errors, are now returning a Result
+- Player configuration is now a custom type with more convenient API
+- Player VideoInfo uses a Fraction instead of (u32,u32) for the framerate and
+  pixel-aspect-ratio
+- VideoFrame API has more consistent API between writable and read-only
+  variants
+- Buffer::copy_into() was added, and ::copy_region() now takes a
+  BufferCopyFlags parameter instead of always using the default flags
+- ChildProxy::set_child_property() takes a &ToValue now to follow the API of
+  Object::set_property() and improve usability
+- Proxy/GhostPad default pad functions use the correct specific pad type now
+  instead of a generic Pad
+- Bus::add_signal_watch_full() takes a Priority for the priority instead of u32
+- Clock::(un)adjust_with_calibration() takes no clock parameter anymore
+
+### Removed
+- FormatValue was removed in favour of GenericFormattedValue and the
+  connected traits and specific format impls
+
+## [0.9.1] - 2017-11-26
+### Fixed
+- Export `FlowError`/`FlowSuccess`, `ClockError`/`ClockSuccess`,
+  `PadLinkError`/`PadLinkSuccess` too
+
+## [0.9.0] - 2017-11-26
+### Added
+- Bindings for (outputting to) the GStreamer logging system
+- Bindings for the GStreamer base library
+- Bindings for all the `Pad` functions to override pad behaviour, and pad task
+  functions
+- Bindings for `StaticCaps` and `StaticPadTemplate`
+- Bindings for `deep-notify` signal on `Object`
+- Support for directly creating `Error`/`Warning`/`Info` `Messages` and posting them
+  from an element with context information (file, line, module, etc.) similar
+  to the C `GST_ELEMENT_ERROR` macro
+- Support for setting custom fields in `Messages`/`Events` during construction
+- Support for creating Buffers out of anything that is `AsRef<[u8]>` or
+  `AsMut<[u8]>`
+- Support for using the `Read` trait on `Adapter`
+- Functions for getting all sink/src/all pads of an `Element`, and all children
+  of a `Bin`
+- Builder for `Caps` and `Structures` in addition to the existing functions
+- `AppSrc`/`AppSink` implement `BaseSrc`/`BaseSink` and `URIHandler`
+- Rust ports of the basic tutorials 1 to 8 from
+  https://gstreamer.freedesktop.org/documentation/tutorials/
+- "Getting started" and "Installation" sections to the README.md
+- "dox" feature for generating documentation for all available configurations
+
+### Fixed
+- `StackTraceFlags` are only available since 1.12
+- Worked around macOS requiring a `NSRunLoop` running on the main thread in all
+  examples and tutorials, to be able to show a window or anything else
+
+### Changed
+- `ClockTime` is now a wrapper around `Option<u64>` to handle the
+  `CLOCK_TIME_NONE` case better. This wrapper implements all the arithmetic
+  and other traits as needed and ensures that no accidential calculations with
+  `CLOCK_TIME_NONE` can happen
+- "Values with format", like in `Duration`/`Position`/`Convert` queries or
+  `Seek` events now return a `FormatValue` type. This contains the actual
+  `Format` together with the value and does any required conversions. This
+  also makes it harder to accidentially mix e.g. values in bytes and time
+- `PadProbeId` does not implement `Clone`/`Copy` anymore
+- Property notify watches return a custom type instead of ulong
+- `Error`/`Warning`/`Info` `Messages` can only be created with specific kinds of
+  `glib::Error` now. Using arbitrary ones does not work
+- `Iterator` bindings were completely rewritten and provide the item type as a
+  generic type parameter now, greatly simplifying its usage
+- All `glib::Values` are now `glib::SendValue` instead, e.g. in `Caps` and
+  `Structures`, as their content must be possible to send to different threads
+  safely
+- `Message::get_src()` can return `None`
+- Allow `None` as `Caps` in `AppSrc`/`AppSink`
+- Allow everything implementing `Into<Option<&str>>` to be used as a pad name
+- Moved `copy()` from `GstRc` directly to `MiniObject`
+- Success/Error enums (like `FlowReturn`, `PadLinkReturn`, `StateChangeReturn`) now
+  implement an `into_result()` function that splits them into a `Result` with
+  the good and bad cases. Also mark them as `#[must_use]` to make it harder to
+  accidentially ignore errors.
+- Error enums implement the `Error` trait
+
+- Many examples use the `failure` crate for error handling now, cleaning up the
+  error handling code quite a bit
+- Lots of other code cleanup, compiler/clippy warning cleanup, etc.
+
+## [0.8.2] - 2017-11-11
+### Fixed
+- Implement StaticType of BufferRef instead of Buffer. Buffer aka
+  GstRc<BufferRef> already implements StaticType if BufferRef does, and
+  without this it was not possible to use Buffers in GValues.
+- Free memory of the appsink/appsrc callbacks with the correct type. It was
+  crashing because of using the wrong type before.
+- Fix documentation URLs in Cargo.toml.
+
+### Added
+- Installation instructions and links to documentation for getting started to
+  README.md.
+
+## [0.8.1] - 2017-09-15
+### Added
+- Implement Send+Sync for Query, Message and Event, and their corresponding
+  Ref types.
+
+### Fixed
+- Constructor for gst_player::Player now works properly with GStreamer 1.12
+  when passing a video renderer or signal dispatcher. There was a reference
+  counting bug.
+- Instead of returning &'static references from functions, return references
+  with a generic, unbound lifetime instead.
+  See https://github.com/rust-lang/rust/pull/42417#issue-233404573
+- Various "unused external crate" warnings and clippy warnings everywhere.
+
+### Changed
+- Remove Cargo.lock from GIT, it's not very useful for library crates.
+- Run everything through latest rustfmt-nightly.
+- Use while-let (instead of loop and if-let) and CLOCK_TIME_NONE (instead of
+  u64::MAX) in the examples.
+
+## [0.8.0] - 2017-08-31
+
+- Initial release of the autogenerated GStreamer bindings. Older versions
+  (< 0.8.0) of the bindings can be found [here](https://github.com/arturoc/gstreamer1.0-rs).
+  The API of the two is incompatible.
+
+[Unreleased]: https://github.com/sdroege/gstreamer-rs/compare/0.11.0...HEAD
+[0.11.0]: https://github.com/sdroege/gstreamer-rs/compare/0.10.2...0.11.0
+[0.10.2]: https://github.com/sdroege/gstreamer-rs/compare/0.10.1...0.10.2
+[0.10.1]: https://github.com/sdroege/gstreamer-rs/compare/0.10.0...0.10.1
+[0.10.0]: https://github.com/sdroege/gstreamer-rs/compare/0.9.1...0.10.0
+[0.9.1]: https://github.com/sdroege/gstreamer-rs/compare/0.9.0...0.9.1
+[0.9.0]: https://github.com/sdroege/gstreamer-rs/compare/0.8.1...0.9.0
+[0.8.2]: https://github.com/sdroege/gstreamer-rs/compare/0.8.1...0.8.2
+[0.8.1]: https://github.com/sdroege/gstreamer-rs/compare/0.8.0...0.8.1
--- a/gstreamer-pbutils/README.md
+++ b/gstreamer-pbutils/README.md
@ -0,0 +1,170 @@
+# gstreamer-pbutils-rs [![crates.io](https://img.shields.io/crates/v/gstreamer.svg)](https://crates.io/crates/gstreamer) [![Build Status](https://travis-ci.org/sdroege/gstreamer-rs.svg?branch=master)](https://travis-ci.org/sdroege/gstreamer-rs)
+
+[GStreamer](https://gstreamer.freedesktop.org/) (Pbutils library) bindings for Rust.
+Documentation can be found [here](https://sdroege.github.io/rustdoc/gstreamer/gstreamer/).
+
+These bindings are providing a safe API that can be used to interface with
+GStreamer, e.g. for writing GStreamer-based applications.
+
+For background and motivation, see the [announcement blogpost](https://coaxion.net/blog/2017/07/writing-gstreamer-applications-in-rust/).
+
+The bindings (since 0.8.0) are autogenerated with [gir](https://github.com/gtk-rs/gir/)
+based on the [GObject-Introspection](https://wiki.gnome.org/Projects/GObjectIntrospection/)
+API metadata provided by the GStreamer project. Older versions before 0.8.0 were manually
+written and the repository can be found [here](https://github.com/arturoc/gstreamer1.0-rs).
+The API of the two is incompatible.
+
+A crate for writing GStreamer plugins in Rust can be found here: https://github.com/sdroege/gst-plugin-rs
+
+## Table of Contents
+1. [Installation](#installation)
+   1. [Linux/BSDs](#installation-linux)
+   1. [macOS](#installation-macos)
+   1. [Windows](#installation-windows)
+1. [Getting Started](#getting-started)
+1. [License](#license)
+1. [Contribution](#contribution)
+
+<a name="installation"/>
+
+## Installation
+
+To build the GStreamer bindings or anything depending on them, you need to
+have at least GStreamer 1.8 and gst-plugins-base 1.8 installed. In addition,
+some of the examples/tutorials require various GStreamer plugins to be
+available, which can be found in gst-plugins-base, gst-plugins-good,
+gst-plugins-bad, gst-plugins-ugly and/or gst-libav.
+
+<a name="installation-linux"/>
+
+### Linux/BSDs
+
+You need to install the above mentioned packages with your distributions
+package manager, or build them from source.
+
+On Debian/Ubuntu they can be installed with
+
+```
+$ apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
+      gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
+      gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
+      gstreamer1.0-libav
+```
+
+Package names on other distributions should be similar.
+Please submit a pull request with instructions for yours.
+
+<a name="installation-macos"/>
+
+### macOS
+
+You can install GStreamer and the plugins via [Homebrew](https://brew.sh/) or
+by installing the [binaries](https://gstreamer.freedesktop.org/data/pkg/osx/)
+provided by the GStreamer project.
+
+#### Homebrew
+
+```
+$ brew install gstreamer gst-plugins-base gst-plugins-good \
+      gst-plugins-bad gst-plugins-ugly gst-libav
+```
+
+#### GStreamer Binaries
+
+You need to download the *two* `.pkg` files from the GStreamer website and
+install them, e.g. `gstreamer-1.0-1.12.3-x86_64.pkg` and
+`gstreamer-1.0-devel-1.12.3-x86_64.pkg`.
+
+After installation, you also need to install `pkg-config` (e.g. via Homebrew)
+and set the `PKG_CONFIG_PATH` environment variable
+
+```
+$ export PKG_CONFIG_PATH="/Frameworks/GStreamer.framework/Versions/Current/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
+```
+
+<a name="installation-windows"/>
+
+### Windows
+
+You can install GStreamer and the plugins via [MSYS2](http://www.msys2.org/)
+with `pacman` or by installing the
+[binaries](https://gstreamer.freedesktop.org/data/pkg/windows/) provided by
+the GStreamer project.
+
+#### MSYS2 / pacman
+
+```
+$ pacman -S pkg-config mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base \
+      mingw-w64-x86_64-gst-plugins-good mingw-w64-x86_64-gst-plugins-bad \
+      mingw-w64-x86_64-gst-plugins-ugly mingw-w64-x86_64-gst-libav
+```
+
+#### GStreamer Binaries
+
+You need to download the *two* `.msi` files for your platform from the
+GStreamer website and install them, e.g. `gstreamer-1.0-x86_64-1.12.3.msi` and
+`gstreamer-1.0-devel-x86_64-1.12.3.msi`.
+
+After installation, you also need to install `pkg-config` (e.g. via MSYS2 or
+from [here](https://sourceforge.net/projects/pkgconfiglite/))
+and set the `PKG_CONFIG_PATH` environment variable
+
+```
+$ export PKG_CONFIG_PATH="c:\\gstreamer\\1.0\\x86_64\\lib\\pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
+```
+
+<a name="getting-started"/>
+
+## Getting Started
+
+The API reference can be found
+[here](https://sdroege.github.io/rustdoc/gstreamer/gstreamer/), however it is
+only the Rust API reference and does not explain any of the concepts.
+
+For getting started with GStreamer development, the best would be to follow
+the [documentation](https://gstreamer.freedesktop.org/documentation/) on the
+GStreamer website, especially the [Application Development
+Manual](https://gstreamer.freedesktop.org/documentation/application-development/).
+While being C-centric, it explains all the fundamental concepts of GStreamer
+and the code examples should be relatively easily translatable to Rust. The
+API is basically the same, function/struct names are the same and everything
+is only more convenient (hopefully) and safer.
+
+In addition there are
+[tutorials](https://gstreamer.freedesktop.org/documentation/tutorials/) on the
+GStreamer website. Many of them were ported to Rust already and the code can
+be found in the
+[tutorials](https://github.com/sdroege/gstreamer-rs/tree/master/tutorials)
+directory.
+
+Some further examples for various aspects of GStreamer and how to use it from
+Rust can be found in the
+[examples](https://github.com/sdroege/gstreamer-rs/tree/master/examples)
+directory.
+
+<a name="license"/>
+
+## LICENSE
+
+gstreamer-rs and all crates contained in here are licensed under either of
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+   http://opensource.org/licenses/MIT)
+
+at your option.
+
+GStreamer itself is licensed under the Lesser General Public License version
+2.1 or (at your option) any later version:
+https://www.gnu.org/licenses/lgpl-2.1.html
+
+<a name="contribution"/>
+
+## Contribution
+
+Any kinds of contributions are welcome as a pull request.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in gstreamer-rs by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.