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