basic pqoi readme file

pqoi/readme.md

@@ -0,0 +1,199 @@
+# Tools for creating and modifying PQOI (*.pqf) files.
+
+PQOI is a image/video/animation file format created specifically
+for RGB565 images and video. In this directory, you'll find:
+
+* cpqoi - creates pqoi files
+* dpqoi - disassembles pqoi files
+* pqoi.h - all the functions needed to add pqoi support in other programs
+
+PQOI files genrally use a .pqf file extension.
+
+## Installation and setup
+
+These programs are written to be used from command lines and scripts in a POSIX-like environment.
+If you're on Windows, I suggest installing a linux image to use them.
+
+In addition to the code in this directory, you'll need:
+
+* a compiler (to compile these tools)
+* make
+* ffmpeg
+* netpbm
+
+Just run "make" in this directory to compile cpqoi and dpqoi.
+
+### A note about netpbm
+The NetPBM that comes with ubuntu and debian is from 2002. It is missing many features and has many bugs.
+If you are on Debian, Ubuntu or one of it's derivatives, install NetPBM from the NetPBM site, or these tools will not work.
+
+# Creating your first PQOI file.
+
+Just run:
+```
+./cpqoi someimage.png >someimage.pqf
+```
+
+This will create a PQOI file from the image, the resolution will be the same as the input.
+If this is too big, we can specify a scaling pipeline, something like:
+
+```
+./cpqoi someinage.png "pamscale -xysize 128 80" >someimage.pqf
+```
+
+This will create a PQF with a maximum size of 128x80 pixels. Any pipeline of pam commands can be used for the scaling.
+For single images, this might not seem very helpful, but scaling pipelines become more important later....
+
+If we want to check the generated PQF file, we can do his:
+```sh
+mkdir tmpdir
+cd tmpdir
+../dpqoi ../someimage.pqf
+```
+
+This will create an image called "IMG00000.png" in the current directory which will contain the image from the PQF file.
+Please note that this will NOT be identical to the original image, as the image data will have been converted to RGB565 and back.
+dpqoi will also print out this:
+
+```
+file IMG00000.png
+```
+
+This is our first hint at PQOIML, the PQOI markup language. More about this below.
+
+# Creating an animated PQOI file.
+
+Just run:
+```sh
+./cpqoi somemovie.mp4 "pamscale -xysize 128 80" >animation.pqf
+```
+
+This will create an animated and looped PQOI file.
+Animated PQF files are basically just concatenated PQF files, with a header which specifies the frame rate.
+
+As before, we can also do the opposite:
+
+```sh
+mkdir tmpdir2
+cd tmpdir2
+../dpqoi ../animation.pqf
+```
+
+This time, many PNG images will be generated, and dpqoi will write out a lot more pqoiml:
+
+```
+label L0
+fps 25:1
+file IMG00000.png
+file IMG00001.png
+file IMG00002.png
+file IMG00003.png
+file IMG00004.png
+.... etc.
+goto L0
+```
+
+This pqoiml is a little more interesting. This uses "label" and "goto" to create a loop, it has several images, and it specifies a frame rate.
+We can save the pqoiml text into a file like this:
+
+```sh
+../dpqoi ../animation.pqf >animation.pqoiml
+```
+
+If we give this pqoiml file as input to cpqoi, it will re-assemble the animation from it's components:
+
+```sh
+../cpqoi animation.pqoiml >animation.pqf
+```
+
+# PQOIML
+
+The PQOI markup language is very simple, here are all the possible commands:
+
+### fps A:B
+
+Specifies the frame rate as a fraction, here are some examples:
+
+```
+fps 25:1  # 25 fps
+fps 24000:1001 # common movie frame rate (23.976 fps)
+fps 30000:1001 # NTSC frame rate (29.97 fps)
+```
+
+### file FILENAME
+
+Imports the image or movie into the PQF.
+Uses the scaling pipeline to scale each image.
+
+### label LABEL
+
+Generate a label. Labels don't actually exist in the output file, as GOTO and IF statements
+just use positions in the file instead.
+
+### goto LABEL
+
+Generates an unconditional jump to the label.
+Looped animations have goto to the beginning at the end.
+
+### if COND goto LABEL
+
+In pqoiml, if statements are very simple, they work just like a goto, but with
+a condition. The conditions are application defined, but are always exactly
+four characters long. The list of conditions supported by ProffieOS has not
+yet been finalized, but this is what is supported so far:
+
+* ison - do the jump if the saber is ignited
+* lock - if we're in normal lockup mode
+* drag - drag lockup mode
+* melt - melt lockup mode
+* A<30 - if A is less than 30
+* A>30 - if A is greather than 30
+* A=30 - if A is equal to 30
+
+Note that "A" is a generic variable, and the meaning of A can be assigned at
+runtime by using a .SCR file. There are 5 possible variables: A, B, C, D, E
+and their values can be battery percent, volume, and other things.
+
+### scaling SCALING PIPELINE
+
+This sets the commands that scales the images. The scaling command is
+not saved in the output file, it's only used when a "file" statement
+is encountered. The scaling pipeline can also be specified on the command line,
+which makes it possible to use the same pqoiml file to generate multiple
+PQF files in different resolutions.
+
+## An example pqoiml file:
+
+This is a pqoiml file for a simple battery overlay:
+
+```
+scaling pamcut -pad 0 0 174 250 | pamflip -r180 | pamcut -pad 0 0 1280 640 | pamflip -r180 | pamscale -xysize 160 80
+
+fps 1:2
+
+label empty
+file 0.png
+label twenty
+file 20.png
+if A<10 goto blink
+if A<40 goto twenty
+
+label fourty
+file 40.png
+if A<40 goto twenty
+if A<60 goto fourty
+
+label sixty
+file 60.png
+if A<60 goto fourty
+if A<80 goto sixty
+
+label eighty
+file 80.png
+if A<80 goto sixty
+
+label full
+if A<90 goto eighty
+file 100.png
+goto full
+```