skinpeel

README.md (5860B)

---

 Skinpeel
 ========
 
 Change vita's lockscreen foreground and background randomly. Based on reverse
 engineering the [fruitpeel][] plugin.
 
 ![screenshot](screenshot.png)
 
 Changes from the original plugin:
 * Only supports firmware 3.60 for now.
 * Uses BC1/DXT1 images instead of 8bpp png files. Generally it should have
   better quality images with reduced memory usage.
 * Random mode: select random bg/fg on every lock.
 * Can also change the foreground image.
 
 Usage
 -----
 
 Use the `convert` tool to convert your images to `.spraw` files.
 
 Add `skinpeel.suprx` under `*main` in your taihen config. Copy the background
 image to `ur0:data/skinpeel/foo/bg.spraw` and the foreground to
 `ur0:data/skinpeel/foo/fg.spraw`.
 
 If you want to randomly use multiple images, create extra directories in
 `ur0:data/skinpeel`. For example, if you have `ur0:data/skinpeel/a` and
 `ur0:data/skinpeel/b`, on each lock the plugin will randomly choose `a` or `b`
 and load the images inside. You can also have multiple image files as long as
 they start with `fg` or `bg` and end with `.spraw`. The plugin will choose a
 directory first, then an fg/bg image later. So, for example with a directory
 structure like this:
 
 ```
 ur0:data/skinpeel
  + foo
    + bg0.spraw
    + bg1.spraw
    + fg0.spraw
    + fg1.spraw
  + bar
    + bg.spraw
    + fg.spraw
 ```
 
 On each lock the plugin will choose randomly between `foo` and `bar`. If it
 chooses `bar`, it will use the `bar/bg.spraw` and `bar/fg.spraw`. However, if it
 chooses `foo`, it will randomly select between `foo/bg0.spraw` and
 `foo/bg1.spraw` for background (and the same for fg).
 
 You can override only the foreground or only the background image, but if you
 have multiple directories, make sure each has the same set of images (i.e.
 either all or none have `bg*.spraw`, and all or none have `fg*.spraw`). Also
 avoid directories without `.spraw` files.
 
 **Note**: to save about 256 KiB of precious ram, make sure to set the lock
 screen background (in the original settings app, Theme & Background -> Start
 Screen) to an image with an exact size of 1024x512 (the content doesn't matter,
 it will be replaced by the plugin anyway). If you did it right, you should have
 a file named `ur0:shell/wallpaper/lock.dds` with a size of `256.12 KB` in
 VitaShell (262272 bytes, to be precise).
 
 Image creation details
 ----------------------
 
 The vita has a screen resolution of 960x544, but the status bar at the top of
 your screen is opaque, so you only have 960x512 pixels for the actual image
 contents. But due to the limitations of the Vita, you need to specify a texture
 with size 1024x512, and it will be scaled back to 960x512 by the Vita. If you
 use the convert tool it will handle all of this automatically, but if you have
 an input image with a different aspect ratio than 15:8, it will crop it.
 
 If you need more control over the creation of the image, here are the steps you
 should take (this assumes you use gimp, but other image editors should work
 too):
 
 1. Select "Rectangle Select Tool" (R), select Fixed Aspect ratio and set aspect
    ratio to 15:8.
 2. Select the region of the image you want to use.
 3. Image -> Crop to selection
 4. Image -> Scale Image, and scale it to 1024x512.
 
 At this point you can export the image to a png and convert it to spraw with
 `convert --no-scale`. (`--no-scale` is important, otherwise it will take the
 middle 960x512 of your image and scale it again.)
 
 Alternatively, you can use DDS images directly. Make sure you set compression
 format to DXT1 and no mipmap. The skinpeel plugin will be able to load `.dds`
 files created this way directly, but it will be a tinly little bit slower.
 
 Convert tool
 ------------
 
 You need a c++ compiler to compile it. Running `compile_convert.sh` on linux
 should produce an executable called `convert`, on other OS you might need to
 tweak it. It can load any images that [stb_image][] can load (jpg, png, tga,
 bmp, gif, pic, pnm, and maybe psd, hdr).
 
 It can either convert a bunch of image files in one go (in this case the
 output file will be the input file but with the extension replaced with
 `.spraw`), or a single file with a custom output name (specified with `-o`).
 
 ```
 Usage: ./convert [options] input_files
  -h --help: print help
  -v --verbose: verbose
  -s --no-scale: do not scale input, it must be already 1024x512
  -f --filter=FILTER: specify scale filter (default, box, triangle, cubic-b-spline, catmull-rom, mitchell)
  -q --quality=QUALITY: specify DXT1 compress quality (0..9, 9 is the best)
  -o --out=FILE: specify output filename
 ```
 
 Compile Vita plugin
 -------------------
 
 Make sure you have [VitaSDK][] installed. Note that I use version
 [1033][vitasdk_1033] of the SDK, it might or might not work with newer versions.
 
 If you have that, make sure the `VITASDK` environment variable is set to the
 correct value and execute `./compile.sh`.
 
 License
 -------
 
 This program is free software. It comes without any warranty, to the extent
 permitted by applicable law. You can redistribute it and/or modify it under the
 terms of the Do What The Fuck You Want To Public License, Version 2, as
 published by Sam Hocevar. See http://www.wtfpl.net/ for more details.
 
 Original code written by me is licensed under WTFPL 2. The converter executable
 incorporates some third party code under permissive licenes:
 
 * [`stb_image.h`][stb_image] and `stb_image_resize.h` by stb. Public domain.
 * [`icbc.h`][icbc] DXT1 encoder. MIT License.
 
 The Vita plugin includes [xoshiro128++][] random number generator (public
 domain).
 
 [fruitpeel]: https://forum.devchroma.nl/index.php/topic,338.0.html
 [stb_image]: https://github.com/nothings/stb/blob/master/stb_image.h
 [vitasdk]: https://github.com/vitasdk
 [vitasdk_1033]: https://github.com/vitasdk/autobuilds/releases?q=master-linux-v1033
 [icbc]: https://github.com/castano/icbc
 [xoshiro128++]: https://prng.di.unimi.it/