B_Pixels v1.0
  Released JUN 2023
 
Reference Manual:
    Table of Contents  
        1) Summary / Introduction
        2) How to use
        3) Slider Explanations
        4) Known Bugs and Troubleshooting
        5) Suggestions and tips
        6) Contact, Legal and Miscellaneous
 
-------------------------------------------------------------
    
1)    Summary:
    
        B_Pixels is an easy way to add various pixelation effects with Blender's compositor. Besides creating simple pixelation effects, it also has functions for patterns that can help in creating effects like screentones and mosaics to your renders or any other images or movies you've made.  Anyone familiar with Blender's compositing nodes will have an easy time dropping it into any project, but for anyone unfamiliar this guide will provide step-by step instructions, as well as an explanation of each setting's functions.
        Thank you for buying B_Pixles, please look forward to more compositing tools from me soon!
     
        -Matt
     
-------------------------------------------------------------     
2)    How to use:
    
        With your Blender Scene
            1. In your Blender file, use "File > Append..." and navigate to this file, B_Pixles.blend
            2. Navigate to "NodeTree” and select "B_Pixel_v01.0"
            3. In the Compositor, use "Add > Group" add "B_Pixel_v01.0"
            4. Plug the "Image" output of your Render Layers into the "Clean_Input" input socket
            5. Add an Image Node with "Add > Image," use it to open one of the provided images from the “ExampleShapes” folder, then plug its "Image" output into the "Pixel_Mask" input socket.
            6. Connect the "Pixelated_Output" output into your composite and viewer nodes, and adjust the setting sliders to your needs.
         
        With an Image or Movie File
            1. In this file's compositing window, disconnect and delete the "Render Layers" Node
            2. Add a Image or Image Sequence node under "Add > Input"
            3. Connect the new node to the "Clean_Input" input socket
                /!\ Be sure that the resolution in your Render Properties is set to the same resolution as your source image
     
-------------------------------------------------------------

3)    Slider Explanations:

    Clean_Input
    -Input for source you want the effect applied to. Usually a Render Layers or Image node.

    PixelSize
    -How large you want each square of pixelization to be, measured in pixels

    Pixel_X
    -Scales each pixel on it's X axis, higher numbers making wider pixels

    Pixel_Y
    -Scales each pixel on it's Y axis, higher numbers making taller pixels

    Pixel_Rotation
    -Rotates the entire pixel pattern by the number of degrees input.
 
    Pixel_XOffset
    -Translates pixelation pattern along the X axis
        /!\ 0 represents each square in its original position, 1 represents each square shifted 1 position screen left
     
    Pixel_YOffset
    -Translates pixelation pattern along the Y axis
    /!\ 0 represents each square in its original position, 1 represents each square shifted 1 position down
     
    Pixel_Mask
    -Determines the shape of each pixel when Mask_Transp is at less than 1.0
    /!\  A square, grayscale image MUST be plugged into this input for B_Pixel to function. You can find images for use in the “ExampleShapes” folder included with B_Pixels

    Mask_Opacity
    -The level of transparency of the Pixel Mask's black areas
     
    Mask_Scale
    -The size of the mask applied to each pixel individually
     
    Mask_Rotation
    -The angle of the mask applied to each pixel individually
     
    Mask_XOffset
    -Moves Pixel Mask pattern independant of the original pixel grid
    /!\  0 represents each Pixel Mask in its original position, 1 represents each Pixel Mask shifted 1 position screen Right
     
    Mask_YOffset
    -Moves Pixel Mask pattern independant of the original pixel grid
    /!\  0 represents each Pixel Mask in its original position, 1 represents each Pixel Mask shifted 1 position Up

-------------------------------------------------------------
     
4) Known Bugs and Troubleshooting

    -Pixel_Mask MUST have an image connected to its socket in order for B_Pixel to function, even if it's not being used. Otherwise, the image will simply appear completely transparent.
    
    -B_Pixels REALLY prefers Moore's numbers (ex. 8, 16, 32, 64, 128, etc.), especially in its Pixel Scaling. While it can create a pixel grid to any size, if you begin seeing any errors or unexpected results, the first step of troubleshooting should be to try setting Pixel_Size to a number from the Moore's set, a number divisible by 8, or at least an even number.
    
    -You may see wrap-around pixels. For example, what should be the final row of pixels on the left side of the image will display in a row of pixels on the right. This is much more likely when Pixel_Size is set to a non-Moore's number, or when using Pixel_XOffset or Pixel_YOffset. This is an expected result of how B_Pixels works and not necessarily a bug. This can be rectified either by adjusting Pixel_XOffset or Pixel_YOffset, or simply by plugging B_Pixel's output into a Scale Node and increasing the size of the result until your wraparound is off-screen.
    
    -As of version 3.5, B_Pixels is incompatible with the Live Compositor. While there is a visible effect, the result is on the whole a big blurry smear. Rely on the compositing view and rendered results.
 
-------------------------------------------------------------
    
5) Suggestions and Tips
    
    -Don't forget, all sliders can be animated!
    
    -Try adding a Value node and connecting it to both the Pixel_Rotation setting and Mask_Rotation sockets together. This will rotate the angle of the pixel array but keep the pattern upright! This is a fun way to create wallpaper-style diagonal patterns
    
    -Usings the Separate RGB node on your image, and then using B_Pixel on each channel before re-combining it will let you create different pixelation patterns for each channel. This is a great way to create a halftone-style newspaper effect!
    
-------------------------------------------------------------

6) Contact, Legal and Miscellaneous

    Created by Matthew Bixler. For questions or comments, please email therealmattbixler@gmail.com
    
    This tool is designed for Blender and is intended for personal and professional use. Released under the GNU General Public License: https://www.gnu.org/licenses/gpl-3.0.html
    
    NFTs are a scam. All modern generative AI image software is built from stolen work.