Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds initial readme. #9

Merged
merged 1 commit into from
Aug 23, 2023
Merged

Adds initial readme. #9

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 23 additions & 160 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,172 +1,35 @@
# OBS Plugin Template
# OBS Composite Blur Plugin

## Introduction
OBS Composite Blur Plugin aims to be a comprehensive blur plugin that provides blur algorithms and types for all levels of quality and computational need. The "composite" in the name is for providing proper compositing of blurring sources with alpha masks. Since OBS sources have no context of the image underneath them, Composite Blur Plugin allows the user to provide a background source that is properly blurred into the resulting feathered edges.

The plugin template is meant to be used as a starting point for OBS Studio plugin development. It includes:
## Blur Algorithms
OBS Composite Blur provides several different algorithms to blur your sources. The blur algorithms are written with performance in mind, using techniques like linear sampling and GPU texture interpolation to stretch what your GPU can do.

* Boilerplate plugin source code
* A CMake project file
* GitHub Actions workflows and repository actions
### Gaussian
A high quality blur algorithm that uses a gaussian kernel to sample/blur. Gaussian sampling results in an aestetically pleasing blur, but becomes computationally intensive at higher blur radius. This plugin supports fractional pixels for Gaussian blur, which allows for smooth animation when using plugins like Move Transition. Additionally, all platforms are supported, however due to how OBS handles OpenGL (MacOS and Linux) vs Direct3D (Windows), the OpenGL implementation is slightly less efficient. The Gaussian Blur Algorithm supports [Area](#area), [Directional](#directional), [Zoom](#zoom), and [Motion](#motion) blur effects.

## Set Up
### Box
Box blur works similar to Gaussian, but uses an equally weighted sample of surrounding pixels. The upside is a more efficient blurring algorithm, at the expense of some quality. With one pass, box blur can cause some blocky artifacts in some cases. This can be mitigated by increasing the number of passes- a 2 pass box blur has nearly the same quality as Gaussian blur. This plugin allows the user to specify up to 5 passes. Similar to Gaussian, this implementation of box blur allows for fractional pixels for smooth animation. The Box Blur Algorithm supports [Area](#area), [Directional](#directional), [Zoom](#zoom), and [Tilt-Shift](#tilt-shift) blur effects.

The plugin project is set up using the included `buildspec.json` file. The following fields should be customized for an actual plugin:
### Pixelate
Pixelate divides the souce into larger pixels, effectively downsampling the image, and giving it a bitmap like appearance. This plugin allows the user to specify the pixel size and shape. Supported shapes are Square, Hexagon, Triangle, and Circle. As with the other algorithms, fractional pixel sizes (blur radius) is supported. The Pixelate Algorithm only supports the [Area](#area) blur effect.

* `name`: The plugin name
* `version`: The plugin version
* `author`: Actual name or nickname of the plugin's author
* `website`: URL of a website associated with the plugin
* `email`: Contact email address associated with the plugin
* `uuids`
* `macosPackage`: Unique (**!**) identifier for the macOS plugin package
* `macosInstaller`: Unique (**!**) identifier for the macOS plugin installer
* `windowsApp`: Unique (**!**) identifier for the Windows plugin installer
## Blur Effects
OBS Composite Blur provides several different blur effects or types, all giving a different feel to the resulting image.

These values are read and processed automatically by the CMake build scripts, so no further adjustments in other files are needed.
### Area
Area blur is the typical 2D blur where pixels are blurred equally in all directions. Inputs are only the blur radius.

### Platform Configuration
### Directional
Directional blur is a blur applied along a single axis, but is blurred in both the positive and negative direction. Inputs are blur radius and the direction angle.

Platform-specific settings are set up in the `platformConfig` section of the buildspec file:
### Motion
Motion blur is similar to [Directional Blur](#directional), however it is applied in
only the positive direction along the blur axis. This yields an image that simulates a camera capturing blur due to motion in a particular direction. Inputs are blur radius and direction angle.

* `bundleId`: macOS bundle identifier for the plugin. Should be unique and follow reverse domain name notation.
### Zoom
Zoom blur is applied away from a center zoom point, and increases the further from the center point the pixel being blurred is. This yields an image that looks like the viewer is zooming into the center zoom point. Inputs are blur radius, and center zoom point location.

### Set Up Build Dependencies

Just like OBS Studio itself, plugins need to be built using dependencies available either via the `obs-deps` repository (Windows and macOS) or via a distribution's package system (Linux).

#### Choose An OBS Studio Version

By default the plugin template specifies the most current official OBS Studio version in the `buildspec.json` file, which makes most sense for plugins at the start of development. As far as updating the targeted OBS Studio version is concerned, a few things need to be considered:

* Plugins targeting _older_ versions of OBS Studio should _generally_ also work in newer versions, with the exception of breaking changes to specific APIs which would also be explicitly called out in release notes
* Plugins targeting the _latest_ version of OBS Studio might not work in older versions because the internal data structures used by `libobs` might not be compatible
* Users are encouraged to always update to the most recent version of OBS Studio available within a reasonable time after release - plugin authors have to choose for themselves if they'd rather keep up with OBS Studio releases or stay with an older version as their baseline (which might of course preclude the plugin from using functionality introduced in a newer version)

On Linux, the version used for development might be decided by the specific version available via a distribution's package management system, so OBS Studio compatibility for plugins might be determined by those versions instead.

#### Windows and macOS

Windows and macOS dependency downloads are configured in the `buildspec.json` file:

* `dependencies`:
* `obs-studio`: Version of OBS Studio to build plugin with (needed for `libobs` and `obs-frontend-api`)
* `prebuilt`: Prebuilt OBS Studio dependencies
* `qt6`: Prebuilt version of Qt6 as used by OBS Studio
* `tools`: Contains additional build tools used by CI

The values should be kept in sync with OBS Studio releases and the `buildspec.json` file in use by the main project to ensure that the plugin is developed and built in sync with its target environment.

To update a dependency, change the `version` and associated `hashes` entries to match the new version. The used hash algorithm is `sha256`.

#### Linux

Linux dependencies need to be resolved using the package management tools appropriate for the local distribution. As an example, building on Ubuntu requires the following packages to be installed:

* Build System Dependencies:
* `cmake`
* `ninja-build`
* `pkg-config`
* Build Dependencies:
* `build-essential`
* `libobs-dev`
* Qt6 Dependencies:
* `qt6-base-dev`
* `libqt6svg6-dev`
* `qt6-base-private-dev`

## Build System Configuration

To create a build configuration, `cmake` needs to be installed on the system. The plugin template supports CMake presets using the `CMakePresets.json` file and ships with default presets:

* `macos`
* Universal architecture (supports Intel-based CPUs as Apple Silicon)
* Defaults to Qt version `6`
* Defaults to macOS deployment target `11.0`
* `macos-ci`
* Inherits from `macos`
* Enables compile warnings as error
* `windows-x64`
* Windows 64-bit architecture
* Defaults to Qt version `6`
* Defaults to Visual Studio 17 2022
* Defaults to Windows SDK version `10.0.18363.657`
* `windows-ci-x64`
* Inherits from `windows-x64`
* Enables compile warnings as error
* `linux-x86_64`
* Linux x86_64 architecture
* Defaults to Qt version `6`
* Defaults to Ninja as build tool
* Defaults to `RelWithDebInfo` build configuration
* `linux-ci-x86_64`
* Inherits from `linux-x86_64`
* Enables compile warnings as error
* `linux-aarch64`
* Provided as an experimental preview feature
* Linux aarch64 (ARM64) architecture
* Defaults to Qt version `6`
* Defaults to Ninja as build tool
* Defaults to `RelWithDebInfo` build configuration
* `linux-ci-aarch64`
* Inherits from `linux-aarch64`
* Enables compile warnings as error

Presets can be either specified on the command line (`cmake --preset <PRESET>`) or via the associated select field in the CMake Windows GUI. Only presets appropriate for the current build host are available for selection.

Additional build system options are available to developers:

* `ENABLE_CCACHE`: Enables support for compilation speed-ups via ccache (enabled by default on macOS and Linux)
* `ENABLE_FRONTEND_API`: Adds OBS Frontend API support for interactions with OBS Studio frontend functionality (disabled by default)
* `ENABLE_QT`: Adds Qt6 support for custom user interface elements (disabled by default)
* `CODESIGN_IDENTITY`: Name of the Apple Developer certificate that should be used for code signing
* `CODESIGN_TEAM`: Apple Developer team ID that should be used for code signing

## GitHub Actions & CI

Default GitHub Actions workflows are available for the following repository actions:

* `push`: Run for commits or tags pushed to `master` or `main` branches.
* `pr-pull`: Run when a Pull Request has been pushed or synchronized.
* `dispatch`: Run when triggered by the workflow dispatch in GitHub's user interface.
* `build-project`: Builds the actual project and is triggered by other workflows.
* `check-format`: Checks CMake and plugin source code formatting and is triggered by other workflows.

The workflows make use of GitHub repository actions (contained in `.github/actions`) and build scripts (contained in `.github/scripts`) which are not needed for local development, but might need to be adjusted if additional/different steps are required to build the plugin.

### Retrieving build artifacts

Successful builds on GitHub Actions will produce build artifacts that can be downloaded for testing. These artifacts are commonly simple archives and will not contain package installers or installation programs.

### Building a Release

To create a release, an appropriately named tag needs to be pushed to the `main`/`master` branch using semantic versioning (e.g., `12.3.4`, `23.4.5-beta2`). A draft release will be created on the associated repository with generated installer packages or installation programs attached as release artifacts.

## Signing and Notarizing on macOS

Plugins released for macOS should be codesigned and notarized with a valid Apple Developer ID for best user experience. To set this up, the private and personal key of a **paid Apple Developer ID** need to be downloaded from the Apple Developer portal:

* On your Apple Developer dashboard, go to "Certificates, IDs & Profiles" and create two signing certificates:
* One of the "Developer ID Application" type. It will be used to sign the plugin's binaries
* One of the "Developer ID Installer" type. It will be used to sign the plugin's installer

The developer certificate will usually carry a name similar in form to

`Developer ID Application: <FIRSTNAME> <LASTNAME> (<LETTERS_AND_NUMBERS>)`

This entire string should be specified as `CODESIGN_IDENTITY`, the `LETTERS_AND_NUMBERS` part as `CODESIGN_TEAM` to CMake to set up codesigning properly.

### GitHub Actions Set Up

To use code signing on GitHub Actions, the certificate and associated information need to be set up as _repository secrets_ in the GitHub repository's settings.

* First, the locally stored developer certificate needs to be exported from the macOS keychain:
* Using the Keychain app on macOS, export these your certificates (Application and Installer) public _and_ private keys into a single .p12 file **protected with a strong password**
* Encode the .p12 file into its base64 representation by running `base64 <NAME_OF_YOUR_P12_FILE>`
* Next, the certificate data and the password used to export it need to be set up as repository secrets:
* `MACOS_SIGNING_APPLICATION_IDENTITY`: Name of the "Developer ID Application" signing certificate
* `MACOS_SIGNING_INSTALLER_IDENTITY`: Name of "Developer ID Installer" signing certificate
* `MACOS_SIGNING_CERT`: The base64 encoded `.p12` file
* `MACOS_SIGNING_CERT_PASSWORD`: Password used to generate the .p12 certificate
* To also enable notarization on GitHub Action runners, the following repository secrets are required:
* `MACOS_NOTARIZATION_USERNAME`: Your Apple Developer account's _Apple ID_
* `MACOS_NOTARIZATION_PASSWORD`: Your Apple Developer account's _generated app password_
### Tilt-Shift
Tilt-Shift blur defines an in-focus plane, specified by a location in the frame, and a thickness. All pixels outside of the in-focus plane have their blur value increased the further away from the plane they are. The resulting image gives a distorted sense of scale, making large objects look like mineature models. When applied to video scenes like a city street, the effect can be significant. Inputs are blur radius, focus plane angle, focus plane location, and focus plane thickness.