Dev

content/getting_started/examples/index.md

@@ -4,8 +4,13 @@ weight = 3
 date= 2024-10-19
 +++
 
-ProPixelizer comes with a number of example scenes to showcase features and show you how to use the package, which can be found in the `ProPixelizer/ExampleAssets` folder.
+ProPixelizer comes with a number of example scenes to showcase features and show you how to use the package, which can be imported into your project via Unity's Package Manager.
+From `Packages: in project`, select the ProPixelizer package, click `Samples` tab and then press 'import'.
+
+![Example of how to install samples](how_to_install.png)
+
 Each example scene also contains a 'readme' in the scene heirachy, which you can inspect to find out more information or further suggestions.
+The examples are described below.
 
 {% example_showcase(name = "Simple", image="simple.png") %}
 A simple scene showing a few different ProPixelizer materials. If you see this scene correctly, you've successfully installed ProPixelizer! 

content/technical_details/_index.md → content/technical/_index.md

@@ -3,4 +3,5 @@ title = "Technical Reference"
 sort_by = "weight"
 weight = 4
 insert_anchor_links = "right"
+aliases = ["/technical_details"]
 +++

content/technical/objectrendersnapable/index.md

@@ -0,0 +1,20 @@
++++
+title = "Object Render Snapable"
+weight = 21
++++
+
+The `Object Render Snapable` MonoBehavior allows the position of objects to be snapped before rendering the frame. Coupled with a [ProPixelizer Camera](@/technical/propixelizer_camera/index.md) this can be used to [eliminate pixel creep](@/usage/eliminate_pixel_creep/index.md). Snapping of object view angles is also supported, allowing you to easily create the look of hand drawn pixel art which typically restricts the number of view directions. The original positions and angles are restored after camera rendering is complete.
+
+![Object Render Snapable preview](ors.png)
+
+### Snapping
+
+- `Snap Position`: enables or disables snapping of the object's position.
+- `Snap Euler Angles`: enables or disables snapping of the object's rotation. A number of different strategies are available:
+    - `World Space Rotation`: the euler angles describing the rotation of the object in world space are snapped to the desired `Angle Resolution`.
+    - `Camera Space Y`: the euler angles describing the rotation of the object are snapped in world space for x and z, and camera space for the Y-axis. For a camera that rotates freely around the y-axis, this will allow objects to appear with a restricted number of view directions, as shown in the gif below.
+
+<img src="anglesnap.gif">
+
+### Pixel Alignment
+

content/technical/propixelizer_camera/index.md

@@ -0,0 +1,33 @@
++++
+title = "ProPixelizer Camera"
+weight = 10
++++
+
+The `ProPixelizerCamera` is a MonoBehavior that should be added to camera objects in your scene. It provides additional control over ProPixelizer's rendering, and performs the position and angle snapping required to [eliminate creep](@/usage/eliminate_pixel_creep/index.md). There are a number of properties available:
+
+<img src="camera.png" />
+
+### Pixelization
+
+The `Pixelization Filter` controls what objects should be pixelated, allowing you to switch between 'hybrid' styles (where only some objects are pixelated) and full screen pixelization.
+- `Full Scene` pixelates the entire scene.
+- `Only ProPixelizer` will only pixelate ProPixelizer materials and shaders, including ones you create [using the ShaderGraph SubTarget](@/usage/shadergraph/index.md).
+
+Additionally, when operating with `Full Scene` additional options are available:
+- `Use Pixel Art Upscaling` will enable or disable use of a pixel art upscaling filter when blitting the low-res target back to the screen. This can be useful to reduce [shimmer artefacts](@/tips_and_tricks/artefacts/index.md)
+- You may choose between a two methods of rendering the low-res target. The `Virtual` camera path is faster, and works by redirecting URP's opaque, transparents and skybox calls into the ProPixelizer low-res target, but may have compatibility issues with other assets. The `Subcamera` path uses a second camera to render the scene at low resolution; it is more widely compatible, but less performant.
+
+### Pixel size
+
+There are several `Mode`s available to determine the pixelization of the low resolution target.
+- `World Space Pixel Size` allows you to specify the size of a low-res pixel in world units. This size will be maintained for different camera orthographic sizes and screen resolutions. This is useful for your objects, characters and world to maintain the same apparent pixelization as you freely pan and zoom the view around them.
+- `Fixed Downscaling Ratio` defines the low-res target resolution as a fixed multiple of the screen resolution. Note that changes in screen resolution will change the apparent pixelisation of the object.
+- `Fixed Target Resolution` allows you to define a fixed height of the low-res target. This is useful if emulating a specific hardware, for example '320p'.
+
+### Fullscreen options
+
+The `Fullscreen Color Grading LUT` allows you to apply color grading and dithering to the entire scene by specifying a color palette LUT. You can use ProPixelizer to create your own. These properties can be specified for individual cameras. _Note: It's still my firm belief that dithering looks better when applied at the object level, so that the dither pattern can move with the object. ProPixelizer now supports both of these approaches, so don't take my word for it - decide for yourself what you like best!_
+
+### Render Feature overrides
+
+These settings can override specific properties of the render feature for each camera, for example to disable ProPixelizer or [pixel expansion](@/usage/pixelization/index.md) for a camera.

content/technical/render_feature/index.md

@@ -0,0 +1,32 @@
++++
+title = "ProPixelizer Render Feature"
+weight = 1
++++
+
+ProPixelizer's Render Feature adds rendering instructions and passes that are required for ProPixelizer to work.
+The settings provide additional controls to tweak ProPixelizer to your needs, as described below:
+
+![Render Feature Inspector View](render_feature.png)
+
+### Pixelization
+
+These properties configure the methods ProPixelizer uses to pixelate the scene.
+
+- `Use Pixel Expansion`: allows pixelated objects to move with apparent sub-pixel motion relative to one another, without pixel creep. I created the method specifically for ProPixelizer, and an overview of how it works can be found here, under Attempt 3. It requires an additional post-process shader to be applied to the scene, but the smooth sub-pixel motion can make certain games feel more responsive.
+
+### Outline Detection Controls
+
+These properties configure properties of the outline and edge detection shaders.
+
+- `Use Depth Testing for ID Outlines`: when enabled, outlines will only be drawn for edge pixels that are in front of their neighbors. This helps achieve the feel of a hand-drawn sprite, for which the outline would not change depending on the geometry in front of it. A comparison of the two settings is shown in the image here; take particular notice of the darker outline drawn over the vehicle inside the red box when Depth Test is off. The `Depth Test Threshold` can be adjusted to make ProPixelizer more or less sensitive to depth testing of ID outlines.
+- `Use Normals For Edge Detection`: enables detection of edges (creases and ridges) using the scene normals. The `Normal Edge Detection Threshold` can be adjusted to change the sensitivity of the edge detection kernel.
+- `Use Depth Testing for Edge Outlines`: controls whether depth testing should also be used for edges, enabling correct edge detection of objects like staircases.
+
+### Editor Scene Tab
+
+- `Editor Pixel Expansion`: when false, disables pixel expansion in the Editor's Scene tab only.
+
+### Debugging
+
+- `Generate Warnings`: allows you to disable warnings generated by ProPixelizer.
+

content/technical/ubershader/index.md

@@ -0,0 +1,48 @@
++++
+title = "Uber Shader"
+weight = 20
++++
+
+The Uber shader is a general purpose object shader provided with ProPixelizer that can be used for a wide variety of visual styles. The shader itself is authored in ShaderGraph using the [ProPixelizer SubTarget](@/usage/shadergraph/index.md), located at `ProPixelizer/ShaderGraph/ProPixelizerUberShader.shadergraph`. Don't forget that you can copy and modify this shadergraph to tweak the shader to your own requirements!
+
+**Note:** _Previous versions of ProPixelizer featured the `PixelizedWithOutline` shader. The Uber shader is a drop-in replacement shader, which has all the features of the old shader while adding many more, eg. Forward+ support, Hybrid renderer support, GPU Instancing. It is recommended to upgrade your `PixelizedWithOutline` materials to the Uber shader._
+
+![Uber shader inspector view](uber.png)
+
+### ProPixelizer Properties
+
+These properties are present for all [ProPixelizer SubTarget](@/usage/shadergraph/index.md) materials, and control aspects of the cel shading and pixelisation.
+
+**Appearance:**
+
+- `Use Color Grading`: when enabled, the material applies the given `Palette` look-up-table, which allows you to apply color palettes and dithering to your object. The `Palette` texture property is a texture look-up table (LUT) used for the color grading. A number of LUTs to emulate well-known devices (eg NES, PAL, GameBoy) are shipped with ProPixelizer, and ProPixelizer provides tools to [create your own](@/usage/palette_tools/index.md). The LUT can also include color dither patterns as demonstrated here. 
+- `Use Dithering`: toggles whether partial alpha (in the range 0 to 1) should be ignored or drawn as dithered transparency.
+
+**Lighting:**
+
+- `Lighting Ramp`: a texture ramp used for cell shading, which helps give a pixel-art aesthetic. When rendering the object, the value of the lit HSV color is used as a coordinate to sample the lighting ramp.
+- `Ambient Light`: fine control over ambient lighting conditions. The `Constant Weight` slider can be used to adjust between only using scene ambient light (0), which uses spherical harmonics, and only using the `Constant Color` (1). Some hand-drawn pixel art styles implicitly assume a fixed constant ambient light, so this option provides an ability to fine tune between those styles and 3D pixel art where ambient light can be included in the object shading.
+
+**Pixelization**
+
+- `Pixel size`: Controls the size of one 'macropixel' when `Use Pixel Expansion` is enabled (see more information [here](@/usage/pixelization/index.md)).
+
+**Outline**
+
+- `ID`: A unique integer in the range (0, 255). Outlines are drawn when pixels have an ID different to those around them. If two objects should have outlines when they meet, give them different IDs (eg, two enemies). If they should not have outlines (eg, a character and their equipment), give them the same ID.
+
+### Surface Inputs
+
+These closely match similar properties from the URP Lit shader.
+
+- `Albedo` texture and `Color`: define the base color of the model before lighting calculations, and default to white if unassigned. The alpha channel of the `Albedo` texture is used for alpha clipping.
+- `Normal Map`: an optional normal map to add shading detail to the model. In general, I find that cel shading in pixel art tends to work best without normal maps and using smooth shading on models, but there are some situations (eg. scenery) where normal maps can be useful.
+- `Emission` texture and `Emission Color`: provide unlit colors for your material. Think laser beams, red eyes on skeletons, etc - anything you want to be bright even when in darkness. The color is an HDR property to support bloom post processing.
+- `DiffuseVertexColorWeight` and `EmissiveVertexColorWeight`: these sliders control whether any vertex colors in the mesh should be used to additionally tint the lit and unlit colors of the mesh. Unity's particle system uses vertex color for 'per particle' coloring. Some Synty models have black vertex colors on some mesh areas.
+- `Alpha Clip Threshold`: the minimum alpha value of the `Albedo` and `Color` required to draw parts of the mesh.
+
+**Outline properties**, for more information on available outline types see [the outline section](@/usage/outlines/index.md).
+
+- `Outline Color`: the color to use for the silhouette outline, with outline strength controlled by the alpha the alpha value; alpha values of 0 can be used for invisible outlines, 1.0 can be used for block color, and fractions to blend with the unoutlined color.
+- `Edge Highlight`: lightens or darken edges detected by inspection of scene normals. Requires that 'Use Normals For Edge Detection' is enabled on the Render Feature. Color values less than 0.5 will darken edges, color values above 0.5 will lighten edges, and values of 0.5 will make no difference.
+- `Edge Bevel Weight`: Controls the strength of edge bevelling, which changes the mesh normals along detected edges to enable light-reactive edges.

content/tips_and_tricks/_index.md

@@ -0,0 +1,6 @@
++++
+title = "Tips and tricks"
+sort_by = "weight"
+weight = 5
+insert_anchor_links = "right"
++++