initial

README.md

@@ -0,0 +1,158 @@
+# Sherlock Confetti
+
+Sherlock Confetti is a lightweight program that displays a confetti animation
+as a top-level overlay on Wayland compositors. It provides a fun and colorful
+visual effect without interfering with your workflow.
+
+<https://github.com/user-attachments/assets/d4e63a6b-ce41-4faa-8a1e-898570056e84>
+
+## Features
+
+- **Wayland-native:** Built specifically for Wayland environments.
+- **Tiling Window Manager Friendly:** Displays on top without disrupting your
+  window layout.
+- **High-performance rendering with WGPU:** Utilizes GPU acceleration for
+  smooth animation.
+- **Shader-driven confetti:** Custom shaders deliver rich, dynamic visual
+  effects.
+- **Multiple Color Palettes:** Choose from a variety of predefined vibrant and
+  pastel palettes.
+- **Standalone or Integrated:** Originally created for the custom launcher
+  [Sherlock](https://github.com/Skxxtz/sherlock), but fully functional as a
+  standalone program.
+
+## Usage
+
+Simply run the program to enjoy confetti animations on your Wayland session. It
+can be integrated or triggered by other applications such as launchers or
+window managers.
+
+```bash
+confetti
+```
+
+## Installation
+
+### Build Dependencies
+- `libxkbcommon`
+
+### Runtime Dependencies
+- `vulkan-icd-loader`
+- `mesa`
+- `wayland`
+- `wayland-protocols`
+
+### <ins>From Source</ins>
+
+To build Confetti from source, follow these steps.<br>
+Make sure you have the necessary dependencies installed:
+
+- `rust` - [How to install rust](https://www.rust-lang.org/tools/install)
+- `git` - [How to install git](https://github.com/git-guides/install-git)
+
+1. **Clone the repository**:
+
+    ```bash
+    git clone https://github.com/skxxtz/sherlock-confetti.git
+    cd sherlock-confetti
+    ```
+
+2. **Build the project**:
+
+    ```bash
+    cargo build --release
+    ```
+
+3. **Install the binary**:
+
+    After the build completes, install the binary to your system:
+
+    ```bash
+    sudo cp target/release/confetti /usr/local/bin/
+    ```
+
+### <ins>From Binary</ins>
+
+Make sure you have the following dependency installed:
+
+- `tar` - [Tar](https://www.gnu.org/software/tar/)
+
+1. **Download the archive containing the latest release**:
+
+    The archive can be found [here](https://github.com/Skxxtz/sherlock-confetti/releases/latest).
+
+2. **Extract the files from the archive**:
+
+    ```bash
+    cd ~/Downloads/
+    tar -xzf sherlock-confetti*.tar.gz
+    ```
+
+    You can use tab-completion or run `ls` to verify the name of the archive.
+
+3. **Install the binary**:
+
+    Now move the binary to a location on your `$PATH` environment variable:
+
+    ```bash
+    sudo mv confetti /usr/local/bin/
+    ```
+
+    Optionally also move the LICENSE file or delete it:
+
+    ```bash
+    sudo mkdir -p /usr/share/doc/confetti
+    sudo mv LICENSE /usr/share/doc/confetti/
+
+    # or, to remove it:
+    rm LICENSE
+    ```
+
+### <ins>Build Debian Package</ins>
+
+To build a `.deb` package directly from the source, follow these steps:<br>
+Make sure you have the following dependencies installed:
+
+- `rust` - [How to install rust](https://www.rust-lang.org/tools/install)
+- `git` - [How to install git](https://github.com/git-guides/install-git)
+
+1. **Install the `cargo-deb` tool**:
+
+    First, you need to install the `cargo-deb` tool, which simplifies packaging Rust projects as Debian packages:
+
+    ```bash
+    cargo install cargo-deb
+    ```
+
+2. **Build the Debian package**:
+
+    After installing `cargo-deb`, run the following command to build the `.deb` package:
+
+    ```bash
+    cargo deb
+    ```
+
+    This will create a `.deb` package in the `target/debian` directory.
+
+3. **Install the generated `.deb` package**:
+
+    Once the package is built, you can install it using:
+
+    ```bash
+    sudo dpkg -i target/debian/confetti_*.deb
+    ```
+
+    You can use tab-completion or `ls target/debian/` to confirm the file name.
+
+    (Make sure to replace the filename if the version number is different.)
+
+## Palettes
+
+Palettes can be selected by running `confetti` with the `--palette <name>`
+flag. The names for available palettes are listed in the graphic below:
+
+<div align="center" style="text-align:center; border-radius:10px;">
+  <picture>
+    <img alt="color palettes" width="100%" style="border-radius: 10px;" src="assets/palettes.png">
+  </picture>
+</div>