README.md
1# slop
2
3slop (Select Operation) is an application that queries for a selection from the user and prints the region to stdout.
4
5## Features
6
7* Hovering over a window will cause a selection rectangle to appear over it.
8* Clicking on a window makes slop return the dimensions of the window, and it's ID.
9* OpenGL accelerated graphics where possible.
10* Supports simple arguments:
11 * Change selection rectangle border size.
12 * Select X display.
13 * Set padding size.
14 * Force window, or pixel selections with the tolerance flag.
15 * Set the color of the selection rectangles to match your theme! (Even supports transparency!)
16 * Remove window decorations from selections.
17* Supports custom programmable shaders.
18* Move started selection by holding down the space bar.
19
20## Practical Applications
21
22slop can be used to create a video recording script in only three lines of code.
23
24```bash
25#!/bin/bash
26slop=$(slop -f "%x %y %w %h %g %i") || exit 1
27read -r X Y W H G ID < <(echo $slop)
28ffmpeg -f x11grab -s "$W"x"$H" -i :0.0+$X,$Y -f alsa -i pulse ~/myfile.webm
29```
30
31You can also take images using imagemagick like so:
32
33```bash
34#!/bin/bash
35slop=$(slop -f "%g") || exit 1
36read -r G < <(echo $slop)
37import -window root -crop $G ~/myimage.png
38```
39
40Furthermore, if you are adventurous, you can create a simple script to copy things from an image itself, unselectable pdf, or just VERY quick rectangular selection or for places where there is no columnar selection (very useful for dataoperators)
41
42You need to have tesseract with support for the specific language, xclip and others are nice if you just want them in clipboard.
43
44```bash
45#!/bin/env bash
46
47imagefile="/tmp/sloppy.$RANDOM.png"
48text="/tmp/translation"
49echo "$imagefile"
50slop=$(slop -f "%g") || exit 1
51read -r G < <(echo $slop)
52import -window root -crop $G $imagefile
53tesseract $imagefile $text 2>/dev/null
54cat $text".txt" | xclip -selection c
55
56```
57
58
59
60If you don't like ImageMagick's import: Check out [maim](https://github.com/naelstrof/maim) for a better screenshot utility.
61
62## Lets see some action
63
64Ok. Here's a comparison between 'scrot -s's selection and slop's:
65
66
67
68
69You can see scrot leaves garbage lines over the things you're trying to screenshot!
70While slop not only looks nicer, it's impossible for it to end up in screenshots or recordings because it waits for DestroyNotify events before completely shutting down. Only after the window is completely destroyed can anything take a screenshot.
71
72## how to install
73
74### Install using your Package Manager (Preferred)
75
76* [Arch Linux: community/slop](https://www.archlinux.org/packages/community/x86_64/slop/)
77* [Void Linux: slop](https://github.com/voidlinux/void-packages/blob/24ac22af44018e2598047e5ef7fd3522efa79db5/srcpkgs/slop/template)
78* [FreeBSD: x11/slop](http://www.freshports.org/x11/slop/)
79* [NetBSD: x11/slop](http://pkgsrc.se/x11/slop)
80* [OpenBSD: graphics/slop](http://openports.se/graphics/slop)
81* [CRUX: 6c37/slop](https://github.com/6c37/crux-ports/tree/3.2/slop)
82* [Gentoo: x11-misc/slop](https://packages.gentoo.org/packages/x11-misc/slop)
83* [NixOS: slop](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/slop/default.nix)
84* [GNU Guix: slop](https://www.gnu.org/software/guix/packages/#slop)
85* [Debian: slop](https://packages.debian.org/sid/slop)
86* [Ubuntu: slop](https://packages.ubuntu.com/slop)
87* [Fedora: slop](https://src.fedoraproject.org/rpms/slop)
88* [Ravenports: slop](http://www.ravenports.com/catalog/bucket_CB/slop/standard/)
89* [Alpine Linux: testing/slop](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/slop)
90* Please make a package for slop on your favorite system, and make a pull request to add it to this list.
91
92### Install using CMake (Requires CMake)
93
94*Note: Dependencies should be installed first: libxext, glew, and glm.*
95
96```bash
97git clone https://github.com/naelstrof/slop.git
98cd slop
99cmake -DCMAKE_INSTALL_PREFIX="/usr" ./
100make && sudo make install
101```
102
103### Shaders
104
105Slop allows for chained post-processing shaders. Shaders are written in a language called GLSL, and have access to the following data from slop:
106
107| GLSL Name | Data Type | Bound to |
108| ---------- | -------------- | ----------------------------------------------------------------------------------------------- |
109| mouse | vec2 | The mouse position on the screen. |
110| desktop | sampler2D | An upside-down snapshot of the desktop, this doesn't update as the screen changes. |
111| texture | sampler2D | The current pixel values of slop's frame buffer. Usually just contains the selection rectangle. |
112| screenSize | vec2 | The dimensions of the screen, where the x value is the width. |
113| position | vec2 attribute | This contains the vertex data for the rectangle. Only contains (0,0), (1,0), (1,1), and (0,1). |
114| uv | vec2 attribute | Same as the position, this contians the UV information of each vertex. |
115
116The desktop texture is upside-down because flipping it would cost valuable time.
117
118Shaders must be placed in your `${XDG_CONFIG_HOME}/slop` directory, where *XDG_CONFIG_HOME* is typically `~/.config/`. This folder won't exist unless you make it yourself.
119
120Shaders are loaded from the `--shader` flag in slop. They are delimited by commas, and rendered in order from left to right. This way you can combine multiple shaders for interesting effects! For example, `slop -rblur1,wiggle` would load `~/.config/slop/blur1{.frag,.vert}` and `~/.config/slop/wiggle{.frag,.vert}`. Then render the selection rectangle twice, each time accumulating the changes from the different shaders.
121
122Enough chatting about it though, here's some example shaders you can copy from [shaderexamples](https://github.com/naelstrof/slop/tree/master/shaderexamples) to `~/.config/slop` to try out!
123
124The files listed to the right of the `|` are the required files for the command to the left to work correctly.
125
126* `slop -r blur1,blur2 -b 100` | `~/.config/slop/{blur1,blur2}{.frag,.vert}`
127
128
129
130* `slop -r wiggle -b 10` | `~/.config/slop/wiggle{.frag,.vert}`
131
132
133
134And all together now...
135
136* `slop -r blur1,blur2,wiggle -b 50 -c 1,1,1` | `~/.config/slop/{blur1,blur2,wiggle}{.frag,.vert}`
137
138
139
140Finally here's an example of a magnifying glass.
141
142* `slop -r crosshair` | `~/.config/slop/crosshair{.frag,.vert}`
143
144
145
146It's fairly easy to adjust how the shaders work by editing them with your favourite text editor. Or even make your own!
147
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}