Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/arvtesh/unityfx.outline
Screen-space outlines for Unity3d.
https://github.com/arvtesh/unityfx.outline
image-effects outline post-effect unity unity3d unityfx
Last synced: 4 days ago
JSON representation
Screen-space outlines for Unity3d.
- Host: GitHub
- URL: https://github.com/arvtesh/unityfx.outline
- Owner: Arvtesh
- License: mit
- Created: 2019-08-18T10:43:45.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2023-05-07T11:29:44.000Z (over 1 year ago)
- Last Synced: 2024-12-27T07:06:23.571Z (4 days ago)
- Topics: image-effects, outline, post-effect, unity, unity3d, unityfx
- Language: C#
- Homepage:
- Size: 1.42 MB
- Stars: 1,290
- Watchers: 16
- Forks: 90
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
# UnityFx.Outline
Channel | UnityFx.Outline |
--------|-----------------|
Github | [](https://github.com/Arvtesh/UnityFx.Outline/releases)
Npm (core + built-in RP) | [](https://www.npmjs.com/package/com.unityfx.outline) 
Npm (Post-processing v2) | [](https://www.npmjs.com/package/com.unityfx.outline.postprocessing) 
Npm (URP) | [](https://www.npmjs.com/package/com.unityfx.outline.urp) 
Npm (HDRP) | TODO
**Requires Unity 2018.4 or higher.**
**Compatible with [Unity Post-processing Stack v2](https://github.com/Unity-Technologies/PostProcessing/tree/v2).**
**Compatible with [Universal Render Pipeline](https://docs.unity3d.com/Packages/[email protected]/manual/index.html).**
**Compatible with [XR](https://docs.unity3d.com/Manual/XR.html) (Multi Pass, Single Pass Instanced).**
**Please ask any questions and leave feedback at the [Unity forums](https://forum.unity.com/threads/screen-space-outline-effect-for-unity-free.836908/).**
## Synopsis
*UnityFx.Outline* implements configurable per-object and per-camera outlines. Both solid and blurred outline modes are supported (Gauss blur). The outlines can be easily customized either through scripts or with Unity editor (both in edit-time or runtime).
Implementation is based on Unity [command buffers](https://docs.unity3d.com/ScriptReference/Rendering.CommandBuffer.html), compatible with [Unity Post-processing Stack v2](https://github.com/Unity-Technologies/PostProcessing/tree/v2) and [Universal Render Pipeline](https://docs.unity3d.com/Packages/[email protected]/manual/index.html), extendable and has no external dependencies.
Supported outline parameters are:
- Color;
- Width (in pixels);
- Type (solid or blurred);
- Intensity (for blurred outlines);
- Depth testing;
- Alpha testing.
Supported platforms:
- Windows/Mac standalone;
- Android;
- iOS;
- WebGL;
- Other platforms (untested).
Please see [CHANGELOG](CHANGELOG.md) for information on recent changes.
## Getting Started
### Prerequisites
You may need the following software installed in order to build/use the library:
- [Unity3d 2018.4+](https://store.unity.com/).
### Getting the code
You can get the code by cloning the github repository using your preffered git client UI or you can do it from command line as follows:
```cmd
git clone https://github.com/Arvtesh/UnityFx.Outline.git
```
### Npm packages
[](https://www.npmjs.com/package/com.unityfx.outline)
[](https://www.npmjs.com/package/com.unityfx.outline.postprocessing)
[](https://www.npmjs.com/package/com.unityfx.outline.urp)
Npm core package is available at [npmjs.com](https://www.npmjs.com/package/com.unityfx.outline). There are dedicated packages for [Post-processing Stack v2](https://github.com/Unity-Technologies/PostProcessing/tree/v2) and [Universal Render Pipeline](https://docs.unity3d.com/Packages/[email protected]/manual/index.html). To use the packages, add the following line to dependencies section of your `manifest.json`. Unity should download and link the package automatically:
```json
{
"scopedRegistries": [
{
"name": "Arvtesh",
"url": "https://registry.npmjs.org/",
"scopes": [
"com.unityfx"
]
}
],
"dependencies": {
"com.unityfx.outline": "0.8.5",
"com.unityfx.outline.urp": "0.5.0",
}
}
```
## Usage
Install the package and import the namespace:
```csharp
using UnityFx.Outline;
```
### Per-camera outlines (built-in RP)
Add `OutlineEffect` script to a camera that should render outlines. Then add and configure as many layers as you need. An outline layer is a group of game objects that share the same outline settings:
```csharp
var outlineEffect = Camera.main.GetComponent();
var layer = new OutlineLayer("MyOutlines");
layer.OutlineColor = Color.red;
layer.OutlineWidth = 7;
layer.OutlineRenderMode = OutlineRenderFlags.Blurred;
layer.Add(myGo);
outlineEffect.OutlineLayers.Add(layer);
```
or
```csharp
var outlineEffect = Camera.main.GetComponent();
// This adds layer 0 (if it is not there) and then adds myGo.
outlineEffect.AddGameObject(myGo);
// Now setup the layer.
var layer = outlineEffect[0];
layer.OutlineColor = Color.red;
layer.OutlineWidth = 7;
layer.OutlineRenderMode = OutlineRenderFlags.Blurred;
layer.Add(myGo);
```
This can be done at runtime or while editing a scene. If you choose to assign the script in runtime make sure `OutlineEffect.OutlineResources` is initialized. Disabling `OutlineEffect` script disables outlining for the camera (and frees all resources used).
Multiple `OutlineEffect` scripts can share outline layers rendered. To achieve that assign the same layer set to all `OutlineEffect` instances:
```csharp
var effect1 = camera1.GetComponent();
var effect2 = camera2.GetComponent();
// Make effect1 share its layers with effect2.
effect1.ShareLayersWith(effect2);
```
### Per-object outlines (built-in RP)
Add `OutlineBehaviour` script to objects that should be outlined (in edit mode or in runtime). Make sure `OutlineBehaviour.OutlineResources` is initialized. You can customize outline settings either via Unity inspector or via script. Objects with `OutlineBehaviour` assigned render outlines in all cameras.
```csharp
var outlineBehaviour = GetComponent();
// Make sure to set this is OutlineBehaviour was added at runtime.
outlineBehaviour.OutlineResources = myResources;
outlineBehaviour.OutlineColor = Color.green;
outlineBehaviour.OutlineWidth = 2;
outlineBehaviour.OutlineIntensity = 10;
```
### Depth testing
By default depth testing is disabled when rendering outlines. This behaviour can be overriden by setting `EnableDepthTesting` flag of `Rander Flags` (either via scripting API or with editor).
```csharp
var outlineSettings = GetComponent();
outlineSettings.OutlineColor = Color.green;
outlineSettings.OutlineWidth = 2;
outlineSettings.OutlineRenderMode = OutlineRenderFlags.Blurred | OutlineRenderFlags.EnableDepthTesting;
```
### Alpha testing
By default alpha testing is disabled when rendering outlines. This behaviour can be overriden by setting `EnableAlphaTesting` flag of `Rander Flags` (either via scripting API or with editor).
```csharp
outlineSettings.OutlineRenderMode = OutlineRenderFlags.EnableAlphaTesting;
```
### Ignore layers
When adding a `GameObject` to outline collection it is often desirable to ignore child renderers in specific layers (for instance, `TransparentFX`). This can be achieved by settings the `IgnoreLayers` mask in outline settings (or through corresponding API).
```csharp
var outlineSettings = GetComponent();
outlineSettings.IgnoreLayerMask = LayerMask.GetMask("TransparentFX", "UI");
```
### Extensibility
There are a number of helper classes that can be used for writing highly customized outline implementations (if neither `OutlineBehaviour` nor `OutlineEffect` does not suit your needs).
All outline implementations use following helpers:
- `OutlineRenderer` is basically a wrapper around `CommandBuffer` for low-level outline rendering.
- `OutlineSettings` is a set of outline settings.
Using these helpers is quite easy to create new outline tools. For instance, the following code renders a blue outline around object the script is attached to in `myCamera`:
```csharp
var commandBuffer = new CommandBuffer();
var renderers = GetComponentsInChildren();
// Any implementation of `IOutlineSettings` interface can be used here instead of `OutlineSettings`.
var settings = ScriptableObject.CreateInstance();
settings.OutlineColor = Color.blue;
settings.OutlineWidth = 12;
// Get outline assets instance. In real app this usually comes from MonoBehaviour's serialized fields.
var resources = GetMyResources();
using (var renderer = new OutlineRenderer(commandBuffer, resources))
{
renderer.Render(renderers, settings, myCamera.actualRenderingPath);
}
myCamera.AddCommandBuffer(OutlineRenderer.RenderEvent, commandBuffer);
```
## Integration with Unity post-processing v2.
[](https://www.npmjs.com/package/com.unityfx.outline.postprocessing)
Install the package, add `Outline` effect to `PostProcessProfile`'s overrides list. Configure the effect parameters, make sure outline resources and layer collection are set:
Assign the configured `PostProcessProfile` to `PostProcessVolume` and that's it!
More info on writing custom post processing effects can be found [here](https://docs.unity3d.com/Packages/[email protected]/manual/Writing-Custom-Effects.html).
## Integration with Universal Render Pipeline (URP).
[](https://www.npmjs.com/package/com.unityfx.outline.urp)
Install the package, add `OutlineFeature` to `ScriptableRendererData`'s list of features. Configure the feature parameters (make sure outline resources reference is set). Outline objects can be selected by layer or explixitly using `OutlineLayerCollection`:
Enable depth texture rendering in `UniversalRenderPipelineAsset` and that's it!
### Integration with High Definition Render Pipeline (HDRP).
[](https://www.npmjs.com/package/com.unityfx.outline.hdrp)
TODO
## Motivation
The project was initially created to help author with his [Unity3d](https://unity3d.com) projects. There are not many reusable open-source examples of it, so here it is. Hope it will be useful for someone.
## Documentation
Please see the links below for extended information on the product:
- [Unity forums](https://forum.unity.com/threads/screen-space-outline-effect-for-unity-free.836908/).
- [CHANGELOG](CHANGELOG.md).
- [SUPPORT](.github/SUPPORT.md).
## Useful links
- [A great outline tutorial](https://willweissman.wordpress.com/tutorials/shaders/unity-shaderlab-object-outlines/).
- [Command buffers tutorial](https://lindenreid.wordpress.com/2018/09/13/using-command-buffers-in-unity-selective-bloom/).
- [Gaussian blur tutorial](https://www.ronja-tutorials.com/2018/08/27/postprocessing-blur.html).
- [Excellent post-processing tutorial](https://catlikecoding.com/unity/tutorials/scriptable-render-pipeline/post-processing/).
## Contributing
Please see [contributing guide](.github/CONTRIBUTING.md) for details.
## Versioning
The project uses [SemVer](https://semver.org/) versioning pattern. For the versions available, see [tags in this repository](https://github.com/Arvtesh/UnityFx.Outline/tags).
## License
Please see the [](LICENSE.md) for details.