From f926cc4943600b9d7b9fdde24dff6b1d5a6f8fee Mon Sep 17 00:00:00 2001
From: Vaxry <vaxry@vaxry.net>
Date: Thu, 7 Mar 2024 18:32:25 +0000
Subject: [PATCH] docs: add md

---
 docs/DEVELOPERS.md    | 11 +++++++
 docs/END_USERS.md     | 14 +++++++++
 docs/MAKING_THEMES.md | 71 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 96 insertions(+)
 create mode 100644 docs/DEVELOPERS.md
 create mode 100644 docs/END_USERS.md
 create mode 100644 docs/MAKING_THEMES.md

diff --git a/docs/DEVELOPERS.md b/docs/DEVELOPERS.md
new file mode 100644
index 0000000..adc058b
--- /dev/null
+++ b/docs/DEVELOPERS.md
@@ -0,0 +1,11 @@
+## Usage
+
+Include `hyprcursor/hyprcursor.h` or `.hpp` depending on your language.
+
+Read the comments of the API functions
+
+Have fun :)
+
+Doxygen soon I hope :P
+
+All props exposed are also explained in MAKING_THEMES.md
\ No newline at end of file
diff --git a/docs/END_USERS.md b/docs/END_USERS.md
new file mode 100644
index 0000000..cb14940
--- /dev/null
+++ b/docs/END_USERS.md
@@ -0,0 +1,14 @@
+## Using a hyprcursor theme
+
+Download a hyprcursor theme and extract it to a new directory in `~/.local/share/icons`.
+
+Make sure the first directory contains a manifest, for example:
+
+```s
+~/.local/share/icons/myCursorTheme/manifest.hl
+```
+
+## Overriding a theme
+
+Set the `HYPRCURSOR_THEME` env to your theme directory,
+so for example to get the above to always load, use `export HYPRCURSOR_THEME = myCursorTheme`.
\ No newline at end of file
diff --git a/docs/MAKING_THEMES.md b/docs/MAKING_THEMES.md
new file mode 100644
index 0000000..ca65870
--- /dev/null
+++ b/docs/MAKING_THEMES.md
@@ -0,0 +1,71 @@
+## Creating a theme
+
+Familiarize yourself with the README of `hyprcursor-util`.
+
+## Creating a theme from an XCursor theme
+
+Download an XCursor theme, extract it, and then use `--extract`, and then on the resulting output, `--create`.
+
+## Creating a theme from scratch
+
+The directory structure looks like this:
+```ini
+directory
+ ┣ manifest.hl
+ ┗ hyprcursors
+   ┣ left_ptr
+     ┣ image32.png
+     ┣ image64.png
+     ┗ meta.hl
+   ┣ hand
+     ┣ image32.png
+     ┣ image64.png
+     ┗ meta.hl
+   ...
+```
+
+### Manifest
+
+The manifest describes your theme, in hyprlang:
+```ini
+name = My theme!
+description = Very cool!
+version = 0.1
+cursors_directory = hyprcursors # has to match the directory in the structure
+```
+
+### Cursors
+
+Each cursor image is a separate directory. In it, multiple size variations can be put.
+
+`meta.hl` describes the cursor:
+```ini
+# what resize algorithm to use when a size is requested
+# that doesn't match any of your predefined ones.
+# available: bilinear, nearest, none. None will pick the closest. Nearest is nearest neighbor.
+resize_algorithm = bilinear
+
+# "hotspot" is where in your cursor the actual "click point" should be.
+# this is in absolute coordinates. x+ is east, y+ is north.
+hotspot_x = 0.0 # this goes 0 - 1
+hotspot_y = 0.0 # this goes 0 - 1
+
+# Define what cursor images this one should override.
+# What this means is that a request for a cursor name e.g. "arrow"
+# will instead use this one, even if this one is named something else.
+define_override = arrow
+define_override = default
+
+# define your size variants.
+# Multiple size variants for the same size are treated as an animation.
+define_size = 64, image64.png
+define_size = 32, image32.png
+
+# If you want to animate it, add a timeout in ms at the end:
+# define_size = 64, anim1.png, 500
+# define_size = 64, anim2.png, 500
+# define_size = 64, anim3.png, 500
+# define_size = 64, anim4.png, 500
+```
+
+Supported cursor image types are png and soon svg.
\ No newline at end of file