From 327e430897e78490aae3fd10378e174a74d8e937 Mon Sep 17 00:00:00 2001 From: profezzorn Date: Wed, 6 Dec 2023 19:20:29 -0800 Subject: [PATCH] basic pqoi readme file --- pqoi/readme.md | 199 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 pqoi/readme.md diff --git a/pqoi/readme.md b/pqoi/readme.md new file mode 100644 index 000000000..7869ee5ca --- /dev/null +++ b/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 +```