From 78fbc9a3305eeeb2058eb35e297a9484e2340f2e Mon Sep 17 00:00:00 2001
From: mob-sakai <12690315+mob-sakai@users.noreply.github.com>
Date: Tue, 11 Mar 2025 17:37:30 +0900
Subject: [PATCH] docs: update readme
close #317
---
Packages/src/README.md | 169 +++++++++++++++++++++++++++++++++--------
1 file changed, 139 insertions(+), 30 deletions(-)
diff --git a/Packages/src/README.md b/Packages/src/README.md
index d0f359c..e3692f7 100644
--- a/Packages/src/README.md
+++ b/Packages/src/README.md
@@ -74,9 +74,10 @@ Combine various filters, such as grayscale, blur, and dissolve, to decorate your
## 🎮 Demo
-
-
+
+

+
[WebGL Demo](https://mob-sakai.github.io/UIEffect/)
@@ -96,7 +97,7 @@ _This package requires **Unity 2020.3 or later**._
```
- To update the package, use Package Manager UI (`Window > Package Manager`) or run the following command with `@{version}`:
```
- openupm add com.coffee.ui-effect@5.3.0
+ openupm add com.coffee.ui-effect@5.6.0
```
### Install via UPM (with Package Manager UI)
@@ -105,7 +106,7 @@ _This package requires **Unity 2020.3 or later**._
- Click `+ > Add package from git URL...` and input the repository URL: `https://github.com/mob-sakai/UIEffect.git?path=Packages/src`

- To update the package, change suffix `#{version}` to the target version.
- - e.g. `https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.3.0`
+ - e.g. `https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.6.0`
### Install via UPM (Manually)
@@ -120,7 +121,7 @@ _This package requires **Unity 2020.3 or later**._
```
- To update the package, change suffix `#{version}` to the target version.
- - e.g. `"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.3.0",`
+ - e.g. `"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.6.0",`
### Install as Embedded Package
@@ -153,6 +154,7 @@ If upgrading from UIEffect v4 to v5, note the following breaking changes:
// v5
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src",
+ "com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#main",
```
2. Import the `v4 Compatible Components` sample from the Package Manager window.
@@ -161,7 +163,7 @@ If upgrading from UIEffect v4 to v5, note the following breaking changes:
3. All v4 components are obsolete.
- v4 `UIEffect` component is now `UIEffectV4` component. Change the reference in the code.
- The `effectArea` property in some components are not supported in v5.
-- `UIShadow`, `UIGradient`, `UIFlip` components are not supported in v5.
+- `UIShadow`, `UIGradient` components are not supported in v5.
- v4 components can be converted to v5 `UIEffect` component by selecting `Convert To UIEffect` from the context menu.

@@ -185,32 +187,58 @@ If upgrading from UIEffect v4 to v5, note the following breaking changes:
### Component: UIEffect
-
-
The `UIEffect` component applies visual effects to UI elements, allowing various effects to be achieved by combining multiple filters.
+
+
+> [!TIP]
+> From the top menu, you can load and save the editor presets or clear settings.
+> For details, refer to the [Runtime/Editor Preset for UIEffect](#runtimeeditor-preset-for-uieffect).
+
+
+
#### Tone Filter
-- **Tone Filter**: `None`, `Grayscale`, `Sepia`, `Nega`, `Retro`, `Posterize`
+
+
+- **Tone Filter**: `None`, `Grayscale`, `Sepia`, `Nega`, `Retro`, `Posterize`
+ 
- **Tone Intensity**: 0.0 (no effect) - 1.0 (full effect).
+
+
#### Color Filter
-- **Color Filter**: `None`, `Multiply`, `Additive`, `Subtractive`, `Replace`, `Multiply Luminance`, `Multiply Additive`, `Hsv Modifier`, `Contrast`
+
+
+- **Color Filter**: `None`, `Multiply`, `Additive`, `Subtractive`, `Replace`, `Multiply Luminance`, `Multiply Additive`, `Hsv Modifier`, `Contrast`
+ 
- **Color Intensity**: 0.0 (no effect) - 1.0 (full effect).
- **Color Glow**: Set the color to glow.
+
+
#### Sampling Filter
-- **Sampling Filter**: `None`, `Blur Fast`, `Blur Medium`, `Blur Detail`, `Pixelation`, `Rgb Shift`, `Edge Luminescence`, `Edge Alpha`
+
+
+- **Sampling Filter**: `None`, `Blur Fast`, `Blur Medium`, `Blur Detail`, `Pixelation`, `Rgb Shift`, `Edge Luminescence`, `Edge Alpha`
+ 
- **Sampling Intensity**: 0.0 (no effect) - 1.0 (full effect).
- **Sampling Width**: The width of the sampling effect.
+
+
#### Transition Filter
-- **Transition Filter**: `None`, `Fade`, `Cutoff`, `Dissolve`, `Shiny`, `Mask`, `Melt`, `Burn`, `Pattern`
+
+
+- **Transition Filter**: `None`, `Fade`, `Cutoff`, `Dissolve`, `Shiny`, `Mask`, `Melt`, `Burn`, `Pattern`
+ 
- **Transition Rate**: 0.0 (no effect) - 1.0 (full effect).
-- **Transition Tex**: The texture used for the transition filter.- **Transition Width**: The width where the transition color is applied.
+- **Transition Tex**: The texture used for the transition filter.
+ - **Scale**, **Offset**, **Speed**, **Rotation**, **Keep Aspect Ratio**, **Reverse**: Additional properties for the texture.
+ - NOTE: `Rotation` and `Keep Aspect Ratio` are shared with `Detail Filter`.
- **Transition Width**: The width where the transition color is applied.
- **Transition Pattern Range**: The range of the pattern.
- **Transition Pattern Reverse**: Reverse the pattern.
@@ -218,23 +246,44 @@ The `UIEffect` component applies visual effects to UI elements, allowing various
- **Transition Color Filter**: Specifies the transition color.
- **Transition Color**: The color of the transition.
- **Transition Color Glow**: Set the transition color to glow.
-- **Transition Auto Play Speed**: The speed of the transition animation. You can use this property to loop the `TransitionRate` without tweener or animation.
+- **Transition Auto Play Speed**: The speed of the transition animation (using shader side `_Time`). You can use this property to loop the `TransitionRate` without tweener or animation.
+
+> [!TIP]
+> **Transition Tex** applies transitions using its alpha channel.
+> If you use `Scale`, `Offset`, or `Speed`, set `Wrap Mode = Repeat` in the texture import settings.
+> For details, refer to the textures included in the built-in presets.
+> 
+
+
#### Target Mode
-- **Target Mode**: `None`, `Hue`, `Luminance`
+
+
+- **Target Mode**: `None`, `Hue`, `Luminance`
+ 
- Restricts the effect application area based on hue or luminance.
- **Target Range**: The range of target hue or luminance.
- **Target Softness**: The softness of the target boundary.
+
+
#### Blend Type
-- **Blend Type**: `Alpha Blend`, `Multiply`, `Additive`, `Soft Additive`, `Multiply Additive`, `Custom`
+
+
+- **Blend Type**: `Alpha Blend`, `Multiply`, `Additive`, `Soft Additive`, `Multiply Additive`, `Custom`
+ 
- `Custom` blend type can be set using the `SrcBlend` and `DstBlend` properties.
+
+
#### Shadow Mode
-- **Shadow Mode**: `None`, `Shadow`, `Shadow3`, `Outline`, `Outline8`, `Mirror`
+
+
+- **Shadow Mode**: `None`, `Shadow`, `Shadow3`, `Outline`, `Outline8`, `Mirror`
+ 
- **Shadow Distance**: Distance of the shadow or outline.
- **Shadow Iteration**: Number of times the shadow or outline is applied.
- **Shadow Color Filter**: Specifies the shadow color.
@@ -246,15 +295,20 @@ The `UIEffect` component applies visual effects to UI elements, allowing various
- **Mirror Offset**: Offset for the mirrored image.
- **Mirror Scale**: Scale of the mirrored image.
+
+
#### Gradation Mode
-- **Gradation Mode**: `None`, `Plain`, `Shiny`
+
+
+- **Gradation Mode**: `None`, `Horizontal`, `HorizontalGradient`, `Vertical`, `VerticalGradient`, `RadialFast`, `RadialDetail`, `Diagonal`, `DiagonalToRightBottom`, `DiagonalToLeftBottom`, `Angle`, `AngleGradient`
+ 
- **Gradation Gradient**: The gradient of the gradation.
- **Gradation Color 1**: The first color of the gradation.
- **Gradation Color 2**: The second color of the gradation.
- **Gradation Offset**: The offset of the gradation range.
- **Gradation Scale**: The scale of the gradation range.
-- **Gradation Rotation**: The rotation of the gradation range.
+- **Gradation Rotation**: The rotation of the gradation range (`Angle` or `AngleGradient`).
> [!TIP]
> `Horizontal Gradient` and `Vertical Gradient` divide the mesh horizontally or vertically and apply a gradient.
@@ -263,32 +317,72 @@ The `UIEffect` component applies visual effects to UI elements, allowing various
> It can be applied to meshes other than Full Rect because it applies the gradient according to the original mesh shape.
> `Gradation Gradient` has two modes, `Blend` and `Fixed`.
+
+
#### Edge Mode
-- **Edge Mode**: `None`, `Plain`, `Shiny`
+
+
+- **Edge Mode**: `None`, `Plain`, `Shiny`
+ 
- **Edge Width**: The width of the edge.
- **Edge Color Filter**: Specifies the edge color.
- **Edge Color**: The color of the edge.
+ - **Edge Color Glow**: Set the shadow color to glow.
- **Edge Shiny Width**: The width of the edge shiny.
-- **Edge Shiny Auto Play Speed**: The speed of the edge shiny.
+- **Edge Shiny Auto Play Speed**: The speed of the edge shiny (using shader side `_Time`).
+
+
+
+#### Detail Filter
+
+
+
+- **Detail Filter**: `None`, `Masking`, `Multiply`, `Additive`, `Replace`, `MuliplyAdditive`
+ 
+- **Detail Intensity**: 0.0 (no effect) - 1.0 (full effect).
+- **Detail Threshold** (`Masking` only): The minimum and maximum alpha values used for masking. The larger the gap
+ between these values, the stronger the softness effect.
+- **Detail Tex**: The texture used for the transition filter.
+ - **Scale**, **Offset**, **Speed**, **Rotation**, **Keep Aspect Ratio**: Additional properties for the texture.
+ - NOTE: `Rotation` and `Keep Aspect Ratio` are shared with `Transition Filter`.
+
+
#### Others
+
+
- **Sampling Scale**: The referencing scale during sampling.
- Larger values are suitable for high-resolution textures.
- **Allow To Modify Mesh Shape**: If enabled, the mesh shape can be modified.
+- **Custom Root**: Use the custom transform for some effects.
+- **Flip**:
+ - `Nothing`
+ - `Horizontal`
+ - `Vertical`
+ - `Effect`: Flip with the effect.
+ - `Shadow`: Flip with the shadow.
+
+> [!TIP]
+> `Transition Filter`, `Gradation Filter`, and `Detail Filter` usually refer to their own `RectTransform` when applying effects.
+> For example, if the mesh shape exceeds the `RectTransform` boundaries, the effect may not be applied correctly.
+> By specifying `Custom Root`, you can refer to the specified transform.
### Component: UIEffectTweener
-
+
The `UIEffectTweener` component animates the effect, enabling easy control over effect animations without the need for an `AnimationClip`.
-- **Culling Mask**: `Tone`, `Color`, `Sampling`, `Transition`
+- **Culling Mask**: `Tone`, `Color`, `Sampling`, `Transition`, `GradiationOffset`, `GradiationRotation`, `EdgeShiny`, `Event`
+- **OnChangeRate** (`Event` only): A event that is triggered when the tweening rate changes.
- **Direction**: `Forward (0.0 -> 1.0)`, `Reverse (1.0 -> 0.0)`
- **Curve**: The curve of the animation.
+- **Separate Reverse Curve**: If enabled, `Reverse Curve` will be used for the reverse direction.
+- **Reverse Curve**: The curve of the reverse animation.
- **Delay**: The delay time before starting the animation.
- **Duration**: The duration of the animation.
- **Interval**: The interval time between the animation.
@@ -296,7 +390,11 @@ The `UIEffectTweener` component animates the effect, enabling easy control over
- Play the animation automatically when the component is enabled.
- If `None` is selected, the animation will not play automatically. You can play it using the `Play`, `PlayForward` or `PlayReverse` method.
- **Reset Time On Enable**: Reset the tweening time when the component is enabled.
-- **Wrap Mode**: `Once`, `Loop`, `PingPongOnce`, `PingPongLoop`
+- **Wrap Mode**:
+ - `Once`: delay -> duration(0-1) -> onComplete
+ - `Loop`: delay -> duration(0-1) -> interval -> ...
+ - `PingPongOnce`: delay -> duration(0-1) -> interval -> duration(1-0) -> onComplete
+ - `PingPongLoop`: delay -> duration(0-1) -> interval -> duration(1-0) -> interval -> ...
- **Update Mode**: `Normal`, `UnscaledTime`, `Manual`
- **On Complete**: A event that is triggered when the animation is completed.
@@ -306,15 +404,24 @@ You can preview the animation using the seek bar and play button.
### Component: UIEffectReplica
-
+
The `UIEffectReplica` component applies visual effects to UI elements by replicating the settings of another `UIEffect` component. This allows the same effect to be applied across multiple UI elements simultaneously.
- **Target**: The target `UIEffect` component to replicate.
-- **Use Target Transform**: Use the target's transform for some effects.
+ > [!TIP]
+ > You can specify a preset as well as an instance as the target for `UIEffectReplica`.
+- **Use Target Transform**: Use the target's transform for some effects.
+ 
+- **Custom Root**: Use the custom transform for some effects.
- **Sampling Scale**: Override the sampling scale.
- **Allow To Modify Mesh Shape**: If enabled, the mesh shape can be modified.
- 
+- **Flip**:
+ - `Nothing`
+ - `Horizontal`
+ - `Vertical`
+ - `Effect`: Flip the effect.
+ - `Shadow`: Flip the shadow.
@@ -365,11 +472,13 @@ Click the `Import` button.
### Runtime/Editor Preset for UIEffect
-
+
You can create and use presets for `UIEffect` components.
-- In the `UIEffect` component inspector, click "Save As" button to save the current settings as an editor preset.
-- Click "Load" button to apply an editor preset.
+
+- Click the `Load` button to apply an editor preset.
+> Click the `Append` button to load only non-default settings from the editor preset.
+- Click the `Save As New` button to save the current settings as an editor preset.
- In the [Project Settings](#project-settings), you can register saved editor presets as runtime presets.
- Runtime presets can be loaded using the `UIEffect.LoadPreset(presetName)` method.