
This directory contains the Android-specific code for building xscreensaver.

It is preliminary, and very much a work in progress.

If you're messing with this, please let us know!

        dennis@panaceasupplies.com
        jwz@jwz.org


To set up your Android development environment:

    Install JDK 7 (http://www.oracle.com/technetwork/java/javase/downloads/)
    Install Android Studio (http://developer.android.com/sdk/)
    Install Android NDK (http://developer.android.com/ndk/downloads)
      Rename or link the "android-ndk-*" directory to "ndk" inside your
      $ANDROID_HOME (the "sdk/" directory that is the parent of
      "build-tools/", etc.)  That is, it should be "sdk/ndk/".

    set $ANDROID_HOME to where your SDK is installed, or
    set "sdk.dir" in project/local.properties.
    On MacOS, the value you want is probably ~/Library/Android/sdk/
    Also set "ndk.dir" in project/local.properties.

To build:

    ./configure
    cd android
    make

    Hopefully an "xscreensaver-debug.apk" file will appear in
    android/project/xscreensaver/build/outputs/apk/.

    Load that onto your device and go to:
      Settings / Display / Daydream
    or just click on the XScreenSaver icon, which is a shortcut to that.

    To create and configure an emulator image, use the GUI tool and and
    give the emulator a name (say, "Nexus_5").

      $ANDROID_HOME/sdk/tools/android avd

      E.g.: Nexus 5, Android 5, Intel Atom x86_64, RAM 2048 VM 64,
        storage 200, use host GPU.

    Configuration options are in $HOME/.android/avd/*.avd/config.ini

    To launch it:

      $ANDROID_HOME/sdk/tools/emulator -avd Nexus_5

    Warning!  On my system at least, the emulator runs out of memory
    when trying to display the Daydream page if all of the savers are
    loaded.  This is troubling.  You can work around this by editing
    your *.avd/config.ini and setting vm.heapSize=128; or by editing
    android/Makefile and paring down the $ANDROID_HACKS list to a
    smaller subset (60 or so with the default heapSize).


    To load it into the currently-running emulator or device:
      $ANDROID_HOME/platform-tools/adb install -r \
        project/xscreensaver/build/outputs/apk/xscreensaver-debug.apk

    Extremely verbose log output, including stack traces:
        $ANDROID_HOME/platform-tools/adb logcat

    Non-fatal log output for only this app:
        $ANDROID_HOME/platform-tools/adb logcat \
          -s xscreensaver:d AndroidRuntime:d libEGL:d

    Note that sometimes "logcat" will just sit there forever saying
    "waiting for device".  This is because the emulator is a piece of
    shit and sometimes decides to just randomly not service connections.
    If you restart the emulator, and wait minutes for the whole damned
    thing to boot up again, it will probably work next time.  Probably.


Directory structure:

    Boilerplate for the Java version of "make":
        project/*gradle*
        project/*.properties
        project/xscreensaver/*gradle*
        project/xscreensaver/build.*
        project/xscreensaver/*.properties

    The other half of the Makefile:
        project/xscreensaver/jni/*.mk

    Source code:
        project/xscreensaver/src/org/jwz/xscreensaver/*.java
        project/xscreensaver/res/layout/*.xml

    Other relevant source code is in ../jwxyz/ and ../hacks/.

    Icons:
        project/xscreensaver/res/drawable-ldpi/
        project/xscreensaver/res/drawable-mdpi/
        project/xscreensaver/res/drawable/

    Files that we generate:

        gen/function-table.h
        project/xscreensaver/AndroidManifest.xml
        project/xscreensaver/res/drawable/*.png
        project/xscreensaver/res/values/settings.xml
        project/xscreensaver/res/values/strings.xml
        project/xscreensaver/res/xml/*.xml
        project/xscreensaver/src/org/jwz/xscreensaver/gen/*.java

    Other files generated as a part of the build process:

        gen/
        project/.gradle/
        project/xscreensaver/build/
        project/xscreensaver/build/outputs/apk/  -- app appears here
        project/xscreensaver/jni/
        project/xscreensaver/libs/
        project/xscreensaver/obj/
        project/xscreensaver/res/
        project/xscreensaver/res/drawable/
        project/xscreensaver/res/values/
        project/xscreensaver/res/xml/
        project/xscreensaver/src/org/jwz/xscreensaver/gen/

When adding a new hack, edit android/Makefile, then "make clean" and "make".


TODO list, and known bugs:

  - See the top of ../jwxyz/jwxyz-gl.c for a low level TODO list,
    but here's what's wrong with the savers from a high level view:

  - Rotation is wonky (on some devices?)

  - The Android emulator is a piece of shit and crashes all the time,
    so it's possible that some of these work fine on real devices.
    I don't actually have an Android device, so I have no idea.

  - As mentioned above, the Android emulator runs out of memory if
    more than about 60 of the Daydreams are installed with the default
    heapSize.  Again, I don't know if this is an issue on real devices.
    I sure hope not.

  - The code that attempts to grab a screen shot before the Daydream begins
    doesn't work.

  - When a saver exits abnormally, we catch the exception and attempt to 
    display the error message in a dialog.  The catch works, but the dialog
    box does not.

  anemone	needs thick lines
  anemotaxis    needs thick lines
  antinspect    crashes emulator, sometimes
  antmaze       crashes emulator, sometimes
  antspotlight	crashes emulator, sometimes
  apple2	text, images into pixmaps doesn't work
  atlantis	crashes emulator, sometimes
  barcode       pixmaps
  binaryring    pixmaps
  blitspin      images
  bouboule      ?
  braid         thick lines
  bsod          pixmaps, XCopyArea problems
  bumps         XPutImage
  carousel      blank
  celtic        thick lines
  circuit	crashes emulator
  cityflow	crashes emulator, sometimes
  compass       thick lines
  crackberg	crashes emulator, sometimes
  cube21	crashes emulator, sometimes
  cubenetic	crashes emulator, sometimes
  cubicgrid	crashes emulator, sometimes
  deluxe        thick lines
  dnalogo       codeword is blank
  dymaxionmap	crashes emulator
  endgame	crashes emulator
  engine        text
  epicycle      thick lines
  flipflop      images
  flipscreen3d  images
  fliptext      text
  fontglide     text
  fuzzyflakes   thick lines
  gflux         images
  glblur        crashes emulator, sometimes
  gleidescope   images
  glhanoi       crashes emulator, but a few seconds in
  glplanet      crashes emulator
  glslideshow   images
  goop          polygons
  halftone      XFillArc crash
  halo          XOR
  hypertorus    crashes emulator
  interaggregate        window background should be white
  jigglypuff    incredibly slow
  jigsaw        crashes emulator
  juggler3d	crashes emulator
  maze          no logo, lines look weird
  mirrorblob    images
  moebius       crashes emulator
  moire2        pixmaps
  molecule	crashes emulator
  mountain      polygons
  munch         XOR
  noseguy       pixmaps
  pacman	launches really slowly; fails at loading XPMs
  pedal         polygons
  phosphor      pixmaps
  photopile     pixmaps
  pipes         blank
  polyhedra	crashes emulator
  polyominoes   pixmaps
  projectiveplane       crashes emulator
  pulsar        crashes emulator
  qix           polygons
  queens	crashes emulator
  rocks         polygons
  skytentacles  crashes emulator
  slip          pixmaps
  sonar		crashes emulator
  speedmine     polygons
  spheremonics  crashes emulator
  splitflap     text
  spotlight     pixmaps
  starfish      polygons
  starwars	crashes emulator
  substrate     background should be white
  surfaces      crashes emulator
  tessellimage  pixmaps
  truchet       thick lines
  twang         background should be black
  unicrud       pixmaps
  xanalogtv     pixmaps
  xjack         blank
  xmatrix       pixmaps
  xrayswarm     thick lines
  zoom          pixmaps
