git.hungrycats.org Git - xscreensaver/blob - android/README

   1
   2 This directory contains the Android-specific code for building xscreensaver.
   3
   4 It is preliminary, and very much a work in progress.
   5
   6 If you're messing with this, please let us know!
   7
   8         dennis@panaceasupplies.com
   9         jwz@jwz.org
  10
  11
  12 To set up your Android development environment:
  13
  14     Install JDK 7 (http://www.oracle.com/technetwork/java/javase/downloads/)
  15     Install Android Studio (http://developer.android.com/sdk/)
  16     Install Android NDK (http://developer.android.com/ndk/downloads)
  17       Rename or link the "android-ndk-*" directory to "ndk" inside your
  18       $ANDROID_HOME (the "sdk/" directory that is the parent of
  19       "build-tools/", etc.)  That is, it should be "sdk/ndk/".
  20
  21     set $ANDROID_HOME to where your SDK is installed, or
  22     set "sdk.dir" in project/local.properties.
  23     On MacOS, the value you want is probably ~/Library/Android/sdk/
  24     Also set "ndk.dir" in project/local.properties.
  25
  26 To build:
  27
  28     ./configure
  29     cd android
  30     make
  31
  32     Hopefully an "xscreensaver-debug.apk" file will appear in
  33     android/project/xscreensaver/build/outputs/apk/.
  34
  35     Load that onto your device and go to:
  36       Settings / Display / Daydream
  37     or just click on the XScreenSaver icon, which is a shortcut to that.
  38
  39     To create and configure an emulator image, use the GUI tool and and
  40     give the emulator a name (say, "Nexus_5").
  41
  42       $ANDROID_HOME/sdk/tools/android avd
  43
  44     Configuration options are in $HOME/.android/avd/*.avd/config.ini
  45
  46     To launch it:
  47
  48       $ANDROID_HOME/sdk/tools/emulator -avd Nexus_5
  49
  50     Warning!  On my system at least, the emulator runs out of memory
  51     when trying to display the Daydream page if all of the savers are
  52     loaded.  This is troubling.  You can work around this by editing
  53     your *.avd/config.ini and setting vm.heapSize=128; or by editing
  54     android/Makefile and paring down the $ANDROID_HACKS list to a
  55     smaller subset (60 or so with the default heapSize).
  56
  57
  58     To load it into the currently-running emulator or device:
  59       $ANDROID_HOME/platform-tools/adb install -r \
  60         project/xscreensaver/build/outputs/apk/xscreensaver-debug.apk
  61
  62     Extremely verbose log output, including stack traces:
  63         $ANDROID_HOME/platform-tools/adb logcat
  64
  65     Non-fatal log output for only this app:
  66         $ANDROID_HOME/platform-tools/adb logcat \
  67           -s xscreensaver:d AndroidRuntime:d libEGL:d
  68
  69     Note that sometimes "logcat" will just sit there forever saying
  70     "waiting for device".  This is because the emulator is a piece of
  71     shit and sometimes decides to just randomly not service connections.
  72     If you restart the emulator, and wait minutes for the whole damned
  73     thing to boot up again, it will probably work next time.  Probably.
  74
  75
  76 Directory structure:
  77
  78     Boilerplate for the Java version of "make":
  79         project/*gradle*
  80         project/*.properties
  81         project/xscreensaver/*gradle*
  82         project/xscreensaver/build.*
  83         project/xscreensaver/*.properties
  84
  85     The other half of the Makefile:
  86         project/xscreensaver/jni/*.mk
  87
  88     Source code:
  89         project/xscreensaver/src/org/jwz/xscreensaver/*.java
  90         project/xscreensaver/res/layout/*.xml
  91
  92     Other relevant source code is in ../jwxyz/ and ../hacks/.
  93
  94     Icons:
  95         project/xscreensaver/res/drawable-ldpi/
  96         project/xscreensaver/res/drawable-mdpi/
  97         project/xscreensaver/res/drawable/
  98
  99     Files that we generate:
 100
 101         gen/function-table.h
 102         project/xscreensaver/AndroidManifest.xml
 103         project/xscreensaver/res/drawable/*.png
 104         project/xscreensaver/res/values/settings.xml
 105         project/xscreensaver/res/values/strings.xml
 106         project/xscreensaver/res/xml/*.xml
 107         project/xscreensaver/src/org/jwz/xscreensaver/gen/*.java
 108
 109     Other files generated as a part of the build process:
 110
 111         gen/
 112         project/.gradle/
 113         project/xscreensaver/build/
 114         project/xscreensaver/build/outputs/apk/  -- app appears here
 115         project/xscreensaver/jni/
 116         project/xscreensaver/libs/
 117         project/xscreensaver/obj/
 118         project/xscreensaver/res/
 119         project/xscreensaver/res/drawable/
 120         project/xscreensaver/res/values/
 121         project/xscreensaver/res/xml/
 122         project/xscreensaver/src/org/jwz/xscreensaver/gen/
 123
 124 When adding a new hack, edit android/Makefile, then "make clean" and "make".
 125
 126
 127 TODO list, and known bugs:
 128
 129   - See the top of ../jwxyz/jwxyz-gl.c for a low level TODO list,
 130     but here's what's wrong with the savers from a high level view:
 131
 132   - Rotation is wonky (on some devices?)
 133
 134   - The Android emulator is a piece of shit and crashes all the time,
 135     so it's possible that some of these work fine on real devices.
 136     I don't actually have an Android device, so I have no idea.
 137
 138   - As mentioned above, the Android emulator runs out of memory if
 139     more than about 60 of the Daydreams are installed with the default
 140     heapSize.  Again, I don't know if this is an issue on real devices.
 141     I sure hope not.
 142
 143   - The code that attempts to grab a screen shot before the Daydream begins
 144     doesn't work.
 145
 146   - When a saver exits abnormally, we catch the exception and attempt to
 147     display the error message in a dialog.  The catch works, but the dialog
 148     box does not.
 149
 150   anemone       needs thick lines
 151   anemotaxis    needs thick lines
 152   antinspect    crashes emulator, sometimes
 153   antmaze       crashes emulator, sometimes
 154   antspotlight  crashes emulator, sometimes
 155   apple2        text, images into pixmaps doesn't work
 156   atlantis      crashes emulator, sometimes
 157   barcode       pixmaps
 158   binaryring    pixmaps
 159   blitspin      images
 160   bouboule      ?
 161   braid         thick lines
 162   bsod          pixmaps, XCopyArea problems
 163   bumps         XPutImage
 164   carousel      blank
 165   celtic        thick lines
 166   circuit       crashes emulator
 167   cityflow      crashes emulator, sometimes
 168   compass       thick lines
 169   crackberg     crashes emulator, sometimes
 170   cube21        crashes emulator, sometimes
 171   cubenetic     crashes emulator, sometimes
 172   cubicgrid     crashes emulator, sometimes
 173   deluxe        thick lines
 174   dnalogo       codeword is blank
 175   dymaxionmap   crashes emulator
 176   endgame       crashes emulator
 177   engine        text
 178   epicycle      thick lines
 179   flipflop      images
 180   flipscreen3d  images
 181   fliptext      text
 182   fontglide     text
 183   fuzzyflakes   thick lines
 184   gflux         images
 185   glblur        crashes emulator, sometimes
 186   gleidescope   images
 187   glhanoi       crashes emulator, but a few seconds in
 188   glplanet      crashes emulator
 189   glslideshow   images
 190   goop          polygons
 191   halftone      XFillArc crash
 192   halo          XOR
 193   hypertorus    crashes emulator
 194   interaggregate        window background should be white
 195   jigglypuff    incredibly slow
 196   jigsaw        crashes emulator
 197   juggler3d     crashes emulator
 198   maze          no logo, lines look weird
 199   mirrorblob    images
 200   moebius       crashes emulator
 201   moire2        pixmaps
 202   molecule      crashes emulator
 203   mountain      polygons
 204   munch         XOR
 205   noseguy       pixmaps
 206   pacman        launches really slowly; fails at loading XPMs
 207   pedal         polygons
 208   phosphor      pixmaps
 209   photopile     pixmaps
 210   pipes         blank
 211   polyhedra     crashes emulator
 212   polyominoes   pixmaps
 213   projectiveplane       crashes emulator
 214   pulsar        crashes emulator
 215   qix           polygons
 216   queens        crashes emulator
 217   rocks         polygons
 218   skytentacles  crashes emulator
 219   slip          pixmaps
 220   sonar         crashes emulator
 221   speedmine     polygons
 222   spheremonics  crashes emulator
 223   splitflap     text
 224   spotlight     pixmaps
 225   starfish      polygons
 226   starwars      crashes emulator
 227   substrate     background should be white
 228   surfaces      crashes emulator
 229   tessellimage  pixmaps
 230   truchet       thick lines
 231   twang         background should be black
 232   unicrud       pixmaps
 233   xanalogtv     pixmaps
 234   xjack         blank
 235   xmatrix       pixmaps
 236   xrayswarm     thick lines
 237   zoom          pixmaps