PDP - Pure Data Packet v0.9 a packet processing library for pure data Copyright (c) by Tom Schouten This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The GNU Public Licence can be found in the file COPYING ------------------------------------------------------------------ This external pd library is a framework for image/video processing (and other raw data packets) that is fast, simple and flexible and as much as possible compatible with the pd messaging system. Features: * packet formats: greyscale and YV12 encoded images, binary cellular automata (CA) * sources: noise, video4linux and quicktime (with audio), CA * sinks: xvideo display, sdl * filters: convolution, biquad time, biquad space, CA * warping: rotate, zoom, stretch * transforms: colour translation/scaling, grey->palette * add, mul, mix, random pixel mix * utility objs: packet register, snapshot, trigger * packet delay line * minimal forth system for defining CA rules (only for mmx) Requirements: * pd * linux * a video4linux device for video input. special support for philips webcam included. * libquicktime (not quicktime4linux!) for quicktime playback. * an X display with XVideo extension or SDL for video display. Documentation: When you use "make install" to install pd, all docs will be in the pd doc directory. Right click on an object and select help for a help patch. The pdp directory in pd's doc contains a reference.txt file which lists all objects and abstractions and an introduction and example section. NOTE: all help patches use a pdp_help_input and pdp_help_output abstraction. you can edit these to choose which input or output object you want for the help patches. Building: ./configure make Options for configure: --enable-mmx compile with mmx support --enable-pwc compile with philips webcam support If pd is not installed in /usr/local you'll have to specify the prefix on the configure command line with ./configure --prefix=dir type make install To install pd in $prefix/lib/pd: the library in externs/ the abstractions in extra/ and the documentation in doc/5.reference and doc/pdp NOTE: If you're not using the standard pd install location, and have everything in a single tree, just untar pdp next to the pd source tree. Bugs: See the TODO file. Apart from the few items listed on top of this file, pdp is fairly stable. If you encounter a crash please consider sending a bug report. Additional Remarks: * The modules that depend on system libraries only get compiled when the configure script can locate them. If compilation or linking fails please let me know. NOTE: If you have libquicktime and quicktime4linux installed, this can give problems with the configure script. Consider removing quicktime4linux. (libquicktime is a drop-in replacement). * The reason i use YV12 and not RGB is simple: it's faster, and for linear operations it doesn't make much difference. Most camera's and codecs use a luma/chroma system, and most video cards support hardware accellerated display. Note that in YUV, the u (Cb) and v (Cr) components can be negative, so saturation after multiplication with a positive (or negative) value produces not only black and white, but also red, green, blue and their complements. In short, in YUV, nonlinear operations have a different effect than in RGB. Another thing: all the spatial operations are not implemented "correctly" because of the subsampling involved. * The image packets are 16bit/component planar. This is to simplify the mmx code and to have a little more headroom and precision for processing. * Packets can be processed in a low priority thread with a dropping mechanism to prevent overload or audio drops, or they can be processed in the main pd thread. This can be set/unset by sending a "thread x" message to pdp_control. Processing in pdp thread is off by default. Use the pd thread for rock solid video timing. Increase the audio latency to avoid dropouts. If you want low audio latency, and don't care about a dropped video frame here and there, switch on the pdp thread. Note that when using the pdp thread, the control flow is no longer depth first. Additinal delays will be introduced. * There have been some requests for an osx port, but i wil probably not do this myself (at least not right now). However, the platform independent part of pdp compiles on darwin, although it is not of much use yet without input and output modules. * Have a look at Yves Degoyon's PiDiP library. It contains some extra effects (from EffecTV and FreeJ), a quicktime recording object, some streaming modules, ... (the list is growing rapidly ;) see http://ydegoyon.free.fr/ * Some quicktime remarks: pdp_qt~ is still a bit experimental, you might try pdp_yqt in yves' lib to see if it works better for you. Also, it seems that libquicktime does not work with compressed headers. The suggested codec is jpeg (photo) and uncompressed audio with the same samplerate as the one pd is using. (hint: compile libquicktime with mmx jpeg support) * Writing new objects is not much different than normal pd externs. Pdp just adds some functions to the pd kernel for package allocation, manipulation and communication. The api is very raw to keep it as simple as possible. In the future there will probably be a layer on top of this that will make things a bit less spartan. * New versions of this package can be found at http://zwizwa.fartit.com/pd/pdp Experimental relases are in the subdirectory test/ Directory structure: abstractions/ some abstractions that use the pdp objects doc/introduction/ getting started with pdp doc/examples/ some example patches doc/objects/ pd style reference documentation include/ header files modules/ pdp module code scaf/ CA extension lib (needs to be compiled separately) system/ core pdp system system/mmx/ mmx assembler files Bugreports, feature suggestions, code, documentation, example patches and general comments and questions are welcome. Have Fun, Tom last modified: 2003/02/24