Merge pull request #1 from zigurous/release/0.4.0

Release/0.4.0

.github/workflows/generate-docs.yml

@@ -0,0 +1,23 @@
+name: Generate Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  generate:
+    name: Docs
+    uses: zigurous/docs/.github/workflows/unity-package.yml@main
+    with:
+      package_title: "Graphics Utils"
+      package_base_path: com.zigurous.graphics
+      package_workflow: generate-docs.yml
+      package_artifact: docs
+    secrets:
+      token: ${{ secrets.DOCS_TOKEN }}

CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2023/06/19
+
+### Added
+
+- New `MeshGenerator` static class to generate procedural meshes
+- New `Triangulator` static class to split polygons into triangles
+- New `HiddenMaterialPropertyDrawer` attribute to hide material properties
+- New `Mesh.RecalculateUV` extension method
+- New texture extension methods
+  - `GetPixelCoordinates`
+  - `GetUVCoordinates`
+  - `Sample(u, v)`
+  - `Sample(rect, point)`
+  - `Sample(bounds, position)`
+  - `SetColor`
+- Context menu added to `SaveMesh` to save directly from the editor
+- Help URLs added to all behaviors
+
+### Changed
+
+- Refactored `TextureDrawer` as a ScriptableObject and a separate `TextureDrawerRenderer` behavior
+- Improved `CombineChildrenMeshes` with better transform matrix, option to set mesh name, and toggle to destroy or disable child game objects
+- Renamed `AutoTile.Submesh` to `AutoTile.SubmeshTiling`
+- Formatting changes
+
+### Removed
+
+- `ShaderProperty` and `AnimatedShaderProperty` (moved to AnimationLibrary package)
+
 ## [0.3.0] - 2021/11/14
 
 ### Added

Documentation~/articles/custom-meshes.md

@@ -0,0 +1,61 @@
+---
+slug: "/manual/custom-meshes"
+---
+
+# Custom Meshes
+
+The **Graphics Utils** package includes a few custom cube meshes.
+
+- `Cube-3.mesh`: cube mesh with 3 submeshes (one for each axis)
+- `Cube-6.mesh`: cube mesh with 6 submeshes (one for each face)
+- `Cube-Inverted.mesh`: cube mesh with inverted normals and triangles (inside-out)
+- `Cube-Tiling.mesh` cube mesh designed specifically for [Material Tiling](/manual/material-tiling)
+
+There are also 3 different scripts to generate these cube meshes at runtime:
+
+- [CubeMesh](/api/Zigurous.Graphics/CubeMesh)
+- [CubeMesh3](/api/Zigurous.Graphics/CubeMesh3)
+- [CubeMesh6](/api/Zigurous.Graphics/CubeMesh6)
+
+<hr/>
+
+## ⭕ Inverting Meshes
+
+Sometimes it is useful to invert a mesh so it renders inside out. This is especially useful for cubes. Inverting a mesh flips the triangles and the normals. The **Graphics Utils** package comes with an [InvertMesh](/api/Zigurous.Graphics/InvertMesh) script that handles this automatically.
+
+You can also manually invert the normals and triangles of a mesh using extension methods:
+
+```csharp
+mesh.InvertNormals();
+mesh.InvertTriangles();
+
+// Returns the inverted values without changing the actual mesh
+Vector3[] normals = mesh.InvertedNormals();
+int[] triangles = mesh.InvertedTriangles();
+```
+
+<hr/>
+
+## 🔰 Combining Meshes
+
+The **Graphics Utils** package includes a script to combine multiple meshes into a single mesh. This can be used to improve rendering performance, or as a way to create custom meshes and turn them into assets. Add the [CombineChildrenMeshes](/api/Zigurous.Graphics/CombineChildrenMeshes) script to the parent game object of children meshes. The combined mesh will be assigned to the mesh filter of the parent object, and the child game objects will either be destroyed or disabled.
+
+You can also manually combine meshes through an extension method:
+
+```csharp
+MeshFilter[] filters = GetComponentsInChildren<MeshFilter>();
+Mesh combinedMesh = filters.CombineMesh();
+```
+
+<hr/>
+
+## 💾 Saving Meshes
+
+Often when generating meshes at runtime, you may want to save that mesh as an asset for future use so you don't need to regenerate them again. The **Graphics Utils** package comes with a [SaveMesh](/api/Zigurous.Graphics/SaveMesh) script that will save a mesh as an asset at runtime.
+
+You can also manually save a mesh through extension methods:
+
+```csharp
+mesh.Save("Custom");
+meshFilter.SaveMesh("Custom");
+```

Documentation~/articles/extension-methods.md

@@ -0,0 +1,15 @@
+---
+slug: "/manual/extension-methods"
+---
+
+# Extension Methods
+
+The **Graphics Utils** package contains dozens of extension methods to provide enhanced support for common Unity classes. See each Scripting API for more information:
+
+#### [Material](/api/Zigurous.Architecture/MaterialExtensions)
+
+#### [Mesh](/api/Zigurous.Architecture/MeshExtensions)
+
+#### [MeshFilter](/api/Zigurous.Architecture/MeshFilterExtensions)
+
+#### [Texture](/api/Zigurous.Architecture/TextureExtensions)

Documentation~/articles/index.md

@@ -0,0 +1,33 @@
+---
+slug: "/manual"
+---
+
+# Graphics Utils
+
+The **Graphics Utils** package provides scripts and utilities for graphics and rendering purposes in Unity projects. The package is still early in development, and more functionality will be added over time. Let us know what other features you would like to see.
+
+<hr/>
+
+## Overview
+
+#### ⚙️ [Installation](/installation)
+
+#### 🧰 [Scripting API](/api/Zigurous.Graphics)
+
+#### 📋 [Changelog](/changelog)
+
+#### ⚖️ [License](/license)
+
+<hr/>
+
+## Reference
+
+#### 🔰 [Custom Meshes](/manual/custom-meshes)
+
+#### ⛰️ [Procedural Generation](/manual/procedural-generation)
+
+#### 🛤️ [Material Tiling](/manual/material-tiling)
+
+#### 🖼️ [Texture Drawers](/manual/texture-drawers)
+
+#### 🔌 [Extension Methods](/manual/extension-methods)

Documentation~/articles/installation.md

@@ -0,0 +1,34 @@
+---
+slug: "/installation"
+---
+
+# Installation
+
+Use the Unity [Package Manager](https://docs.unity3d.com/Manual/upm-ui.html) to install the **Graphics Utils** package.
+
+1. Open the Package Manager in `Window > Package Manager`
+2. Click the add (`+`) button in the status bar
+3. Select `Add package from git URL` from the add menu
+4. Enter the following Git URL in the text box and click Add:
+
+```http
+https://github.com/zigurous/unity-graphics-utils.git
+```
+
+<hr/>
+
+## 🏷️ Namespace
+
+Import the package namespace in each script or file you want to use it. You may need to regenerate project files/assemblies first.
+
+```csharp
+using Zigurous.Graphics;
+```
+
+<hr/>
+
+## 💻 Source Code
+
+The source code for the **Graphics Utils** package is in the following repository:
+
+- https://github.com/zigurous/unity-graphics-utils

Documentation~/articles/material-tiling.md

@@ -0,0 +1,17 @@
+---
+slug: "/manual/material-tiling"
+---
+
+# Material Tiling
+
+One of the most powerful features included in the **Graphics Utils** package is the ability to auto tile materials based on the object's scale. In doing so, new materials are created that are unique to the object. This makes the workflow of creating materials for tiled objects effortless. Without this feature, you often end up creating dozens of variants of a material just to change the tiling values for different objects.
+
+Add the [AutoTile](/api/Zigurous.Graphics/AutoTile) script to the object you want to tile. The main property that is usually edited is `submeshes`. Each element in the array indicates how a submesh of the mesh is tiled, such as which axis the object is tiled on, the unit scale of the object, the texture offset, etc. For example, a plane is usually tiled around the Y+ axis, has a unit scale of 10, and only 1 submesh.
+
+<hr/>
+
+## 🕋 Cube Tiling
+
+When tiling cubes, the [AutoTile](/api/Zigurous.Graphics/AutoTile) script gives the best results when used with the `Cube-Tiling.mesh` asset instead of Unity's default cube mesh. This mesh asset is split into 3 separate submeshes so you can tile each axis independently from the others. The mesh also has custom UV coordinates so the materials are tiled from the center of each axis. Using the custom tiling mesh, the script should be set up with 3 submeshes tiled around the X+, Y+, and Z+ axis, respectively, and the unit scale set to 1.
+
+<img src="../images/tiling.jpg" width="360px"/>

Documentation~/articles/procedural-generation.md

@@ -0,0 +1,38 @@
+---
+slug: "/manual/procedural-generation"
+---
+
+# Procedural Generation
+
+The **Graphics Utils** package provides a utility class to generate procedural meshes at runtime. For example, use the [MeshGenerator](/api/Zigurous.Graphics/MeshGenerator) class to create a new procedural mesh that forms a grid of points.
+
+```csharp
+Mesh mesh = MeshGenerator.Create(64, 64);
+```
+
+This is a useful starting point to create more complex meshes, such as procedural terrain. The [MeshGenerator](/api/Zigurous.Graphics/MeshGenerator) class allows you to provide your own custom vertex generation function to create these more complex meshes.
+
+```csharp
+void GenerateTerrain()
+{
+    Mesh terrain = MeshGenerator.Create(64, 64, VertexGenerator);
+}
+
+void VertexGenerator(int x, int y, float u, float v)
+{
+    // sample terrain height using a noise function
+    float height = Mathf.PerlinNoise(x, y);
+    return new Vector3(x, height, y);
+}
+```
+
+<hr/>
+
+## 💎 Triangulation
+
+Sometimes it is useful to split a polygon into triangles in order to generate a custom mesh for the polygon. The [Triangulator](/api/Zigurous.Graphics/Triangulator) class provides this utility. Pass in the points that form the polygon, and the indices of the triangles will be returned.
+
+```csharp
+Vector2[] polygon; // array of points that form a polygon
+int[] triangles = Triangulator.Triangulate(polygon);
+```

Documentation~/articles/texture-drawers.md

@@ -0,0 +1,38 @@
+---
+slug: "/manual/texture-drawers"
+---
+
+# Texture Drawers
+
+The **Graphics Utils** package includes a base class for drawing textures at runtime. It provides the boilerplate code for creating and drawing new textures programmatically.
+
+Create a new class that inherits from [TextureDrawer](/api/Zigurous.Graphics/TextureDrawer) and override the function `SetPixels(Texture2D)` to complete the implementation.
+
+Since [TextureDrawer](/api/Zigurous.Graphics/TextureDrawer) is a ScriptableObject, you'll want to add the `[CreateAssetMenu]` attribute to your class so you can save an instance of the class as an asset in your project using Unity's asset menu.
+
+```csharp
+[CreateAssetMenu]
+public class CustomTextureDrawer : TextureDrawer
+{
+    public override void SetPixels(Texture2D texture)
+    {
+        // Handle setting the pixel colors here...
+    }
+}
+```
+
+<hr/>
+
+## 🖼️ Rendering
+
+The **Graphics Utils** package comes with a script to quickly render the result of a [TextureDrawer](/api/Zigurous.Graphics/TextureDrawer). This is an optional, but useful script to preview the texture without having to write any other code to manually assign the texture to a material.
+
+Add the [TextureDrawerRenderer](/api/Zigurous.Graphics/TextureDrawerRenderer) script to any game object that contains any type of Renderer component. Assign the texture drawer you want to use and customize any other options you'd like. You can even render the texture in the editor without having to run the game.
+
+<hr/>
+
+## 🏁 Checkerboard
+
+The **Graphics Utils** package includes a script [CheckerboardTextureDrawer](/api/Zigurous.Graphics/CheckerboardTextureDrawer) as a sample implementation. It is, of course, a fully functional script that draws a checkerboard pattern. This can be used however you desire, and there are even a number of customization options available.
+
+To create a new checkerboard pattern texture, use the asset menu `Create > Zigurous > Graphics > Checkerboard Texture Drawer`.

Documentation~/data/header.json

@@ -0,0 +1,18 @@
+[
+  {
+    "name": "Manual",
+    "path": "/manual"
+  },
+  {
+    "name": "Scripting API",
+    "path": "/api"
+  },
+  {
+    "name": "Changelog",
+    "path": "/changelog"
+  },
+  {
+    "name": "License",
+    "path": "/license"
+  }
+]