updating pdp to current version 0.12.2

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

1 files changed, 136 insertions, 53 deletions

diff --git a/README b/README
index df1d7d6..589d961 100644
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-PDP - Pure Data Packet v0.9
+PDP - Pure Data Packet v0.12.2
 a packet processing library for pure data
 
 Copyright (c) by Tom Schouten <pdp@zzz.kotnet.org>
@@ -26,30 +26,47 @@ 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 YV12 encoded images,
-  binary cellular automata (CA)
-* sources: noise, video4linux and quicktime (with audio), CA
-* sinks: xvideo display, sdl
+* 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
-* minimal forth system for defining CA rules (only for mmx)
+* 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.
-* an X display with XVideo extension or SDL for video display.
+* libpng for png image loading/saving
+* an X display with XVideo extension, glx or SDL for video display.
 
 
 Documentation:
@@ -72,54 +89,80 @@ make
 
 Options for configure:
 --enable-mmx		compile with mmx support
---enable-pwc		compile with philips webcam 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=dir
+./configure --prefix=/prefix
 
 type
 
 make install
 
-To install pd in $prefix/lib/pd: the library in externs/
+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.
+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. If you encounter a crash please consider
-sending a bug report.
+file, pdp is fairly stable: i am unaware of crash bugs. If you encounter 
+a crash please consider sending a bug report.
 
 
-Additional Remarks: 
+PiDiP Is Definitely In Pieces
 
-* 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).
+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.
 
-* 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.
+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/
 
-* 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. 
+* 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 
@@ -131,32 +174,69 @@ 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/
+* 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. (hint: compile libquicktime with
-mmx jpeg support)
+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. In the future there will probably be a layer on
-top of this that will make things a bit less spartan.
+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.
 
-* New versions of this package can be found at
-http://zwizwa.fartit.com/pd/pdp
-Experimental relases are in the subdirectory test/
 
 
 Directory structure:
@@ -166,10 +246,12 @@ 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)
+modules/		pd object code
+opengl/			opengl extension lib (experimental)
+scaf/			CA extension lib
+guile/			scheme extension lib
 system/			core pdp system
-system/mmx/		mmx assembler files
+
 
 
 
@@ -181,4 +263,5 @@ Have Fun,
 Tom
 
 
-last modified: 2003/02/24
+last modified: 2003/07/20
+