mirror of
https://github.com/processing/processing4.git
synced 2026-06-16 04:26:26 +02:00
cleaning up documentation for libraries and build howto
This commit is contained in:
benfry
@@ -14,11 +14,9 @@ HOW TO BUILD PROCESSING ON YOUR FAVORITE PLATFORM
|
||||
|
||||
+ cvs - used for version control
|
||||
|
||||
+ g++ and gcc-mingw - used to build processing.exe
|
||||
+ make, gcc-mingw, and g++ - used to build processing.exe
|
||||
(this will also pull in gcc-core)
|
||||
|
||||
+ make
|
||||
|
||||
+ perl - use this version, activestate or other distros have trouble
|
||||
|
||||
+ unzip, zip - for dealing with archives
|
||||
|
||||
@@ -1,11 +1,8 @@
|
||||
LIBRARIES IN PROCESSING
|
||||
|
||||
these instructions are now out of date, and will be fixed hopefully soon...
|
||||
(2 april 2005)
|
||||
|
||||
Some basic instructions on how libraries work with Processing.
|
||||
(I'm also adding to this as people have trouble with it.. Pretty soon
|
||||
it's gonna be an outrageous mess!)
|
||||
(I'm also adding to this as people have trouble with it..
|
||||
Pretty soon it's gonna be an outrageous mess!)
|
||||
|
||||
Libraries are a new feature that are present only in revisions 70
|
||||
and higher. Before revision 70, users could place any sort of code
|
||||
@@ -15,22 +12,67 @@ revisions 70 and higher, but the use of the new "library" system is
|
||||
encouraged where that makes sense for your project.
|
||||
|
||||
A Processing library can be any sort of Java code that's been
|
||||
given a package name and packed into a jar file. It can also
|
||||
implement the "PLibrary" interface, and register itself with
|
||||
a PApplet to get notification of when events happen in the sketch,
|
||||
for instance whenever draw() is called or a key is pressed.
|
||||
given a package name and packed into a jar file. It can also register
|
||||
itself with the parent applet to get notification of when events
|
||||
happen in the sketch, for instance whenever draw() is called or a
|
||||
key is pressed.
|
||||
|
||||
Most libraries may not need that much functionality, but they
|
||||
may want to implement the DISPOSE call, which is called as the
|
||||
applet is closed (this isn't totally working in 71 but it will
|
||||
be soon). Many libraries, especially those with native code,
|
||||
may want to implement the dispose() call, which is called as the
|
||||
applet is closed. Many libraries, especially those with native code,
|
||||
need this to properly shut down.
|
||||
|
||||
|
||||
...
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
A very basic library example:
|
||||
|
||||
|
||||
package libraryexample;
|
||||
|
||||
public class BoringLibrary {
|
||||
PApplet parent;
|
||||
|
||||
public BoringLibrary(PApplet parent) {
|
||||
this.parent = parent;
|
||||
parent.registerDispose(this);
|
||||
}
|
||||
|
||||
public void dispose() {
|
||||
// anything in here will be called automatically when
|
||||
// the parent applet shuts down. for instance, this might
|
||||
// shut down a thread used by this library.
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
LIBRARY METHODS
|
||||
|
||||
public void pre()
|
||||
method that's called just after beginFrame(), meaning that it
|
||||
can affect drawing.
|
||||
|
||||
public void draw()
|
||||
method that's called at the end of draw(), but before endFrame().
|
||||
|
||||
public void mouseEvent(MouseEvent e)
|
||||
called when a mouse event occurs in the parent applet
|
||||
|
||||
public void keyEvent(KeyEvent e)
|
||||
called when a key event occurs in the parent applet
|
||||
|
||||
public void post()
|
||||
method called after draw has completed and the frame is done.
|
||||
no drawing allowed.
|
||||
|
||||
public void size(int width, int height)
|
||||
this will be called the first time an applet sets its size, but
|
||||
also any time that it's called while the PApplet is running.
|
||||
|
||||
public void stop()
|
||||
can be called by users, for instance movie.stop() will shut down
|
||||
a movie that's being played, or camera.stop() stops capturing
|
||||
@@ -42,9 +84,24 @@ this should only be called by PApplet. dispose() is what gets
|
||||
called when the host applet is stopped, so this should shut down
|
||||
any threads, disconnect from the net, unload memory, etc.
|
||||
|
||||
...
|
||||
To register any of these methods with the parent, call
|
||||
parent.registerPre(this) or whatever the name of the function
|
||||
is that you'd like to use.
|
||||
|
||||
Structure of a Library
|
||||
Note that making things "public" is extremely important.
|
||||
|
||||
Also note that you can only draw inside of pre(), draw(),
|
||||
mouseEvent(), or keyEvent() otherwise you may run into trouble.
|
||||
pre() and draw() happen while legitimate drawing is taking
|
||||
place, and the mouse/key events happen just before draw()
|
||||
events are called, they're queued up by the host applet
|
||||
until it's safe to draw.
|
||||
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
STRUCTURE
|
||||
|
||||
The Sonia library by Amit Pitaru is a good example here. To make a
|
||||
library called sonia, you create a folder called "sonia" and within
|
||||
@@ -68,7 +125,9 @@ application=sonia.jar,JSynClasses.jar,JSynV142.dll,libJSynV142.jnilib
|
||||
This will include sonia.jar for applets, because in a web browser, the
|
||||
DLL files must be installed separately along with JSynClasses.jar.
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Using Other Java Code As A Library
|
||||
|
||||
@@ -91,7 +150,9 @@ complexity for the developers of library code (who will generally be
|
||||
more advanced users) is traded for great simplicity by the users,
|
||||
since Processing is intended to target beginning programmers.
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Import Statements and How They Work
|
||||
|
||||
@@ -110,7 +171,9 @@ Bottom line, if you want packages from the other .jar to be loaded by
|
||||
Processing, then you need to put those .class files into the main .jar
|
||||
file for the library (sonia/library/sonia.jar in this case).
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Import Statements and the Code Folder
|
||||
|
||||
@@ -118,7 +181,9 @@ The code folder works differently, and every package inside every .jar
|
||||
found in the code folder is simply added to the import statements by
|
||||
the preprocessor. The user never sees this, it just happens magically.
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Creating .jar Files For Your Library
|
||||
|
||||
@@ -145,7 +210,9 @@ jar -cf core.jar processing
|
||||
or with the command line info-zip utility:
|
||||
zip -r core.jar processing
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
The "Import Library" Menu Item
|
||||
|
||||
@@ -153,7 +220,9 @@ All this does is add the "import yourlibrary.*;" statement to the top
|
||||
of your sketch. If you've handwritten the import statements, then
|
||||
there's no need to use "Import Library".
|
||||
|
||||
...
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Getting a UnsupportedClassVersionError? (especially with Java 1.5)
|
||||
|
||||
@@ -170,92 +239,69 @@ shouldn't be with Processing anyway, since most likely you want to
|
||||
make things work on Java 1.1)
|
||||
|
||||
The fix is to compile with "-target 1.1" which will create class
|
||||
files that are compatible with Java 1.1. This is absolutely necessary
|
||||
for any code that will run in a browser, since approximately
|
||||
two-thirds of average web users are still using Microsoft's Java 1.1.4
|
||||
JVM (as of November 2004).
|
||||
files that are compatible with Java 1.1. This is necessary for any
|
||||
code that will run in a browser, since approximately 30-40% of web
|
||||
users are still using Microsoft's Java 1.1.4 JVM (as of April 2005).
|
||||
|
||||
|
||||
.....................................................................
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Example Library
|
||||
ADDING YOUR OWN LIBRARY EVENTS
|
||||
|
||||
This is a skeleton for how a library sets itself up and registers a
|
||||
few calls. See PLibrary.java for more details on specific callbacks
|
||||
that are used by libraries.
|
||||
So that your library can notify the host applet that something
|
||||
interesting has happened, this is how you implement an event
|
||||
method in the style of serialEvent, serverEvent, etc.
|
||||
|
||||
|
||||
/**
|
||||
* All libraries must be inside a package to be used with Processing.
|
||||
* Packages can be somewhat annoying, but they're necessary in later
|
||||
* versions of Java and it's a useful way to keep track of what's used
|
||||
* by a Processing sketch.
|
||||
*/
|
||||
package your.library.name;
|
||||
public class FancyLibrary {
|
||||
Method fancyEventMethod;
|
||||
|
||||
public YourLibrary(PApplet parent) {
|
||||
// your library init code here...
|
||||
|
||||
// needed for the PApplet and PLibrary objects
|
||||
import processing.core.*;
|
||||
|
||||
|
||||
/**
|
||||
* Skeleton class for a library implementation, intends to show
|
||||
* how constructors, setup(), attach(), and a couple calls work.
|
||||
*
|
||||
* Reference for each specific function can be found in PLibrary.java.
|
||||
*/
|
||||
public class AmazingIO implements PLibrary {
|
||||
|
||||
PApplet parent;
|
||||
|
||||
|
||||
/**
|
||||
* Used when an app uses Class.forName() to invoke this feller.
|
||||
* If so, the subsequent newInstance() call will need to be
|
||||
* followed by setup(PApplet parent) or PApplet.attach().
|
||||
* in order to properly connect this guy.
|
||||
*/
|
||||
public AmazingIO() { }
|
||||
|
||||
|
||||
/**
|
||||
* Use instead of calling attach() explicitly.
|
||||
*/
|
||||
public AmazingIO(PApplet iparent) {
|
||||
iparent.attach(this);
|
||||
// check to see if the host applet implements
|
||||
// public void fancyEvent(FancyLibrary f)
|
||||
try {
|
||||
fancyEventMethod =
|
||||
parent.getClass().getMethod("fancyEvent",
|
||||
new Class[] { FancyLibrary.class });
|
||||
} catch (Exception e) {
|
||||
// no such method, or an error.. which is fine, just ignore
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Called by PApplet.attach() or explicitly by the user
|
||||
* who thinks they're more important than that.
|
||||
*/
|
||||
public void setup(PApplet parent) {
|
||||
this.parent = parent; // useful to keep track of
|
||||
|
||||
parent.registerCall(this, PRE);
|
||||
parent.registerCall(this, POST);
|
||||
// then later, to fire that event
|
||||
public void makeEvent() {
|
||||
if (fancyEventMethod != null) {
|
||||
try {
|
||||
fancyEventMethod.invoke(parent, new Object[] { this });
|
||||
} catch (Exception e) {
|
||||
System.err.println("Disabling fancyEvent() for " + name +
|
||||
" because of an error.");
|
||||
e.printStackTrace();
|
||||
fancyEventMethod = null;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
public void pre() {
|
||||
// do something cool
|
||||
}
|
||||
|
||||
|
||||
public void draw() {
|
||||
// do something cooler
|
||||
}
|
||||
|
||||
|
||||
public void size(int w, int h) { }
|
||||
|
||||
public void post() { }
|
||||
|
||||
public void mouse(MouseEvent event) { }
|
||||
|
||||
public void key(KeyEvent e) { }
|
||||
|
||||
public void dispose() { }
|
||||
}
|
||||
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
NAMING
|
||||
|
||||
Libraries should not be prefixed with "P" the way that the core
|
||||
Processing classes are, i.e. it's tempting to prefix everything
|
||||
that way to identify it with processing, but we'd like to reserve
|
||||
that naming for "official" things that are inside processing.core.
|
||||
|
||||
Similarly, please don't using processing.* as the prefix for your
|
||||
library. We'd like to keep that name space clear for official
|
||||
things as well.
|
||||
|
||||
|
||||
//////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
Ben Fry, Last updated 16 April 2005
|
||||
@@ -28,11 +28,11 @@ ABOUT REV 0083 -
|
||||
sets up a spotlight at a position, with a direction and an angle
|
||||
|
||||
+ lightFalloff(constant, linear, quadratic)
|
||||
will change the falloff for the last light addressed. default
|
||||
setting is lightFalloff(1, 0, 0)
|
||||
will change the falloff for any lights that follow.
|
||||
default setting is lightFalloff(1, 0, 0)
|
||||
|
||||
+ lightSpecular(r, g, b)
|
||||
sets the specular color of this light
|
||||
sets the specular color for any lights that follow.
|
||||
|
||||
+ ambient(), emissive(), specular() set the material properties
|
||||
of shapes. they take the same form as fill() and stroke().
|
||||
@@ -71,6 +71,9 @@ ABOUT REV 0083 -
|
||||
|
||||
- nfc() joins the nf() family to format integers and floats with commas.
|
||||
|
||||
- linux version returns, with several fixes, and now handles
|
||||
(warns about) libstdc++ incompatabilities.
|
||||
|
||||
|
||||
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||||
|
||||
|
||||
+20
-16
@@ -43,6 +43,16 @@ X fix linux bugs with placement
|
||||
X lots of dist script tweaking and messing with jikes libs
|
||||
o should loadPixels be grabPixels? (nope)
|
||||
|
||||
saturday evening
|
||||
X update processing/build/howto.txt
|
||||
X add 'make' to list of things that should be installed
|
||||
X update libraries/howto.txt
|
||||
o should we queue lib events until the end of loop?
|
||||
X nope, libraries can handle that themselves,
|
||||
X and queue events by registering for draw or whatever they'd like
|
||||
X lib could call queueEvent with the args
|
||||
X then call them inside post()
|
||||
|
||||
|
||||
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||||
|
||||
@@ -52,25 +62,19 @@ _ get simon's new lighting code
|
||||
_ rename video.Camera to video.Video ?
|
||||
_ VideoInput VideoOutput, SoundInput, SoundOutput or AudioInput/AudioOutput
|
||||
|
||||
|
||||
non-coding tasks (for beta)
|
||||
casey tasks
|
||||
_ new bboard? archive the old one, remove bugs sections
|
||||
_ environment reference
|
||||
_ consolidate readme.txt, revisions.txt
|
||||
_ bugzilla: move bugs.txt and todo.txt into bugzilla
|
||||
_ update processing/build/howto.txt
|
||||
_ add 'make' to list of things that should be installed
|
||||
_ update libraries/howto.txt
|
||||
_ should we queue lib events until the end of loop?
|
||||
_ nope, libraries can handle that themselves,
|
||||
_ and queue events by registering for draw or whatever they'd like
|
||||
_ lib could call queueEvent with the args
|
||||
_ then call them inside post()
|
||||
_ list of changes since rev 69? run through revisions.txt
|
||||
|
||||
non-coding tasks
|
||||
_ scrubbing all the code to include proper license and copyright info
|
||||
_ documenting things that will be broken for beta
|
||||
_ opengl set() functions.. though get() probably ok
|
||||
_ stop button with external apps
|
||||
_ java 1.1 support
|
||||
_ consolidate readme.txt, bugs.txt, info.html (faq)
|
||||
_ document things that will be broken for beta
|
||||
_ opengl set() functions.. though get() probably ok
|
||||
_ stop button with external apps
|
||||
_ java 1.1 support
|
||||
_ setup bugzilla, move legit bugs there, non-bugs to readme
|
||||
|
||||
//
|
||||
|
||||
|
||||
Reference in New Issue
Block a user