processing4/android/about.txt

Understanding changes in the Android version of processing.core:
A guide for the excited, hopeful, weary, and confused.


[ mouse, keys, input ]

+ For compatability, mouseX and mouseY work similar to the original API, 
  and always contain the most recent mouse position. In addition, the
  motionX, motionY, pmotionX, pmotionY, and motionPressure events can be
  used to track relative motion (the native way Android handles input).
  Unlike mouseX/mouseY, those variables are also float values.

+ The mouseButton variable is not available, for perhaps obvious reasons.

+ Watch out for rollovers. While commonly used in mouse-based interfaces, 
  they don't make any sense for touch interfaces. Lots of sketches (most
  of them, really) will need to be rewritten for use on Android to make 
  better use of the affordances given by the hardware.

+ To use the virtual keyboard, hold down the MENU key on the device. This 
  is an Android default, but some users might not be familiar with it.

+ The 'back' key works similar to ESC in the desktop version of Processing.
  (Pressing ESC in the emulator actually emulates hitting the 'back' key.)
  By default, this will exit your application. If you want to do something
  smarter, override keyPressed() and set 'key' to 0 so that the key
  doesn't get picked up by the base class: 

  void keyPressed() {
    // doing other things here, and then:
    if (key == KeyEvent.KEYCODE_BACK) {
      key = 0;  // don't quit by default
    }
  }

+ The keyEvent and mouseEvent variables are not available. If you want to 
  work with event objects, you'll need to override the key and motion handlers:

  public boolean onTouchEvent(MotionEvent event) {
    // your code here

    // if you want the variables for motionX/motionY, mouseX/mouseY etc.
    // to work properly, you'll need to call super.onTouchEvent().
    return super.onTouchEvent(event);
  }

  The key methods work in a similar fashion:

  public boolean onKeyDown(int code, KeyEvent event) {
    return super.onKeyDown(code, event);
  }
    
  public boolean onKeyUp(int code, KeyEvent event) {
    return super.onKeyDown(code, event);
  }

  These three functions behave a bit differently than their counterparts in
  java.awt, so make sure you know what you're doing before messing with them.

  The reason that the variables are not kept around is because the KeyEvent
  and MotionEvent objects are reused, which means they can't be reused without
  an expensive clone operation. And because it's so rare that they're used
  in Processing code, it's better to simply remove them and let advanced users
  who would otherwise rely on the events to handle the overrides themselves.

+ Constants for ALT, CONTROL, and SHIFT are not present. SHIFT may come back, 
  but the other two don't exist on Android.

[ emulator, screen, orientation ] 

+ The emulator stays running, even after you hit stop. This is because it 
  takes a fortnight to launch the emulator. You don't have that kind of time.

+ Once size() is implemented, it may be used as a hint for whether the emulator
  should open in portrait or landscape mode. (It may not, since this would add
  complexity, and you have to rotate physical devices by hand anyway.) Use 
  keypad 7 or keypad 9 to rotate the emulator one direction or another. 
  If you want to lock orientation to one direction, you can use either of 
  these Android API commands:
  setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
  setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);

+ Use screenWidth and screenHeight instead of screen.width and screen.height. 
  Both variables have been added to the desktop version of processing.core, 
  where the 'screen' variable has been deprecated. Aside from this being more
  consistent with the rest of the Processing API, the java.awt.Dimension type
  that's used for 'screen' is not present on Android.


[ developing on android ]

+ We're only supporting Android 2.0.1 and later. 

+ Performance reminds me a lot of Java performance on desktop machines when
  we first started the project in 2001. Most Processing sketches will benefit
  significantly from the JIT that's rumored to arrive by Summer 2010. There 
  are some things that we can speed up, but short of writing everything in 
  native code, we'll be praying for enhancements to the Android platform. 

+ Android seems to have a very shallow stack depth, perhaps ~32 calls. 
  As a result, you might get StackOverflowError in code that worked fine
  with the Java version of Processing.

+ You cannot use .gz files in the data or assets folder, because Android 
  wants to compress the files itself.


[ general notes and practices ] 

+ Using createFont() (instead of loadFont) can help improve text quality, 
  particularly with 2D rendering. Use PFont.list() to get a list of available
  fonts on the system, and select one of those, or include a .ttf or .otf 
  file in the data directory of your sketch. If you use createFont() on a
  typeface that is not installed, rendering quality will be poor.

+ Accuracy of colors is more limited on Android. Most screens will not be 
  full 24-bit color, which especially shows up with gradients, highly detailed
  color sketches, or when using a lot of transparency. With gradients, you
  might see banding of colors, or when using transparency, you might see 
  halos or visual artifacts left behind. These are just mathematical artifacts
  due to how colors are handled, due to limitations of the screen.


[ api changed, gone, or forgotten ] 

+ The package for the core library remains processing.core on Android. 
  Early releases used processing.android.core in an attempt to avoid 
  confusion between the two platforms. Unfortunately, this requires all
  libraries--even those that make only basic use of PApplet features--
  to maintain separate sets of code for each. Because this would needlessly
  affect nearly all libraries, we've decided to just use the same package
  naming. This makes us cringe a little, but the alternative is perpetual
  annoyance at maintaining separate code bases for libraries for which
  only the package imports differ. In practice, there is little chance for
  processing.core packages for both platforms to ever collide with one
  another, since they require completely separate classpaths to build.

+ beginRecord, endRecord, beginRaw, endRaw are not available. There are no
  plans to include them, because it doesn't make sense to use them to export
  geometry on a handheld or portable device.

+ Registering methods (registerPost(), registerDraw(), etc) is not supported.
  Too much overhead for too little benefit.

+ All cursor-related methods have been removed. (They don't make sense in 
  a touch-controlled interface.)

+ The all-lowercase version of arraycopy() (deprecated from the desktop 
  version) has been removed.

+ The (long since) deprecated openStream() method has been removed. Use
  createInput().

+ PImage.image is PImage.bitmap, to reflect that a different object type 
  is there, in spite of its identical purpose.

+ PFont.font is PFont.typeface, similar as above.

+ The 'online' variable is not available. It's for applets to determine 
  whether they're running online or not, which doesn't make sense on
  Android, where there's no such thing as an applet.