checking in pdp 0.12.4 from http://zwizwa.fartit.com/pd/pdp/pdp-0.12.4.tar.gz

svn path=/trunk/externals/pdp/; revision=4231

1 files changed, 267 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..7ced23a
--- /dev/null
+++ b/README
@@ -0,0 +1,267 @@
+PDP - Pure Data Packet v0.12.4
+a packet processing library for pure data
+
+Copyright (c) by Tom Schouten <pdp@zzz.kotnet.org>
+
+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.
+
+This distro contains the main pdp library and 3 extension libs:
+* pdp_scaf (in directory scaf/)
+* pdp_opengl (in directory opengl/)
+* pdp_guile (in directory guile)
+
+Features:
+
+* packet formats: greyscale and YCrCb encoded images,
+  binary cellular automata (CA), textures, render buffers,
+  matrices.
+* sources: noise, video4linux and quicktime (with audio), CA, plasma
+* sinks: xvideo display, sdl, glx display
+* 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, loop, ..
+* and more.. (see doc/reference.txt)
+
+Optional features
+
+* cellular automata simulator and effects processor with
+  built in forth extension language (only for mmx)
+* opengl 3d processing (gem like, but built around packets)
+* embedded guile interpreter
+
+See the README files in the scaf/ opengl/ and guile/ dirs for more
+info on the extension libraries.
+
+
+Requirements:
+
+* pd
+* linux
+* libgsl
+* a video4linux device for video input. special support for 
+philips webcam included.
+* libquicktime (not quicktime4linux!) for quicktime playback.
+* libpng for png image loading/saving
+* an X display with XVideo extension, glx 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		force pdp_v4l to use philips web cam
+
+If pd is not installed in /usr/local you'll have to
+specify the prefix on the configure command line with
+
+./configure --prefix=/prefix
+
+type
+
+make install
+
+To install pdp in $prefix/lib/pd: the library in externs/
+the abstractions in extra/ and the documentation in doc/5.reference
+and doc/pdp
+
+You can also try the "buildall" script. This will configure, build
+and install the whole distribution. It works for intel/mmx.
+
+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,
+or set the prefix dir to the location of the pd source.
+
+
+Bugs:
+
+See the TODO file. Apart from the few items listed on top of this
+file, pdp is fairly stable: i am unaware of crash bugs. If you encounter 
+a crash please consider sending a bug report.
+
+
+PiDiP Is Definitely In Pieces
+
+Have a look at Yves Degoyon's PiDiP library, the must have addition
+to the basic pdp library. It contains a lot of extra effects (from 
+EffecTV and FreeJ), a quicktime recording object, streaming modules,
+ascii art objects ... (the list is growing rapidly ;)
+Yves also did a gem2pd and a pdp2gem object to connect pdp and gem
+together.
+
+http://ydegoyon.free.fr/
+
+
+Acknowledgements
+
+PDP is no longer a one man show. Many thanks to the people who 
+directly or indirectly contributed to this project. Either by 
+writing a giant extension lib (thanks Yves) or by contributing code 
+snippets (Thanks Martin, CK), or by giving mental support, feedback, 
+bug reports and ideas. 
+
+I also wish to thank the GEM crew. This project borrows a lot of ideas 
+and some code from the GEM project. And while i'm at it, i wish to
+thank everyone who contributed code to the PD project as a whole and
+the people that are very helpful at answering questions on the mailing
+list.
+
+Last but not least i wish to thank Miller for making the PD project
+open source. If that didn't happen i wouldn't know what i'd be doing
+now :)
+
+
+Some Remarks: 
+
+* New versions of this package can be found at
+http://zwizwa.fartit.com/pd/pdp
+Experimental relases are in the subdirectory test/
+
+* 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 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. 
+
+* 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.
+
+* Pdp runs on osx, using an x server (apple or fink) and libquickime 
+(fink). pdp_xv does not work yet. Once apple includes xv support in
+their x server, it should. Until then, use pdp_glx for output.
+
+* 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. You can use other codecs, but i've
+found this one to perform the best. (hint: compile libquicktime with
+mmx jpeg support) Try to avoid the mpga codec. It is haunted.
+
+* 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.
+
+* Since version 0.11 there is a type system used for identifying a
+packet type and performing type conversion. A type is represented
+by a symbol, with subtypes separated by the "/" character. I.e.
+"image/grey/320x240" is a grey 16 bit/component image with dimensions
+320 by 240. For conversions a wildcard can be specified. I.e.
+"image/*/*" which matches image type packets with all encodings
+and dimensions.
+
+* Since version 0.12 there are 2 different image data types: "image/*/*"
+and "bitmap/*/*". The image type is the native 16 bit/component pdp
+type. It supports the subtypes "image/grey/*": one channel grey
+scale images, "image/YCrCb/*": luma/chroma packets with subsampled
+chroma planes and "image/multi/*": a multi channel planar format (i.e.
+to store 3 or 4 channel rgb or rgba data). Almost all processors
+use this data type. The bitmap type is an intermediate type which
+can contain standard fourcc encoded 8 bit/component images i.e.
+"bitmap/rgb/*", "bitmap/yv12/*", "bitmap/grey/*". Currently no processors
+support this type natively, so you have to use pdp_convert to convert
+them to "image/*/*".
+
+* 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. Since 0.10 there is a pdp_base object you can
+derive your objects from. Have a look at pdp_add, pdp_gain and 
+pdp_noise to see how it works. There is not much documentation, but
+i do my best to keep things clean so the code and the header files
+should get you started. You can always just send me an email for info,
+or ask on the pd-dev list. Since version 0.12 there is a simple forth
+scripting language in pdp. This is far from finished, but it should
+make pdp programming a lot easier.
+
+* Philips webcam detection is now automatic. However this requires a 
+fairly recent kernel (one which includes the pwc driver version 8.6 
+or higher). If you have a pwc and pdp_v4l does not display a
+"pwc detected" message, you can conifigure with --enable-pwc. This
+forces pdp_v4l to use the pwc api extensions.
+
+
+
+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/		pd object code
+opengl/			opengl extension lib (experimental)
+scaf/			CA extension lib
+guile/			scheme extension lib
+system/			core pdp system
+
+
+
+
+Bugreports, feature suggestions, code, documentation, example patches
+and general comments and questions are welcome.
+
+Have Fun,
+
+Tom
+
+
+last modified: 2003/07/20
+