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 the file local.properties.
  23     On MacOS, the value you want is probably ~/Library/Android/sdk/
  24     Also set "ndk.dir" in 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/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         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         *gradle*
  83         *.properties
  84         xscreensaver/*gradle*
  85         xscreensaver/build.*
  86         xscreensaver/*.properties
  87
  88     The other half of the Makefile:
  89         xscreensaver/jni/*.mk
  90
  91     Source code:
  92         xscreensaver/src/org/jwz/xscreensaver/*.java
  93         xscreensaver/res/layout/*.xml
  94
  95     Other relevant source code is in ../jwxyz/ and ../hacks/.
  96
  97     Icons:
  98         xscreensaver/res/drawable-ldpi/
  99         xscreensaver/res/drawable-mdpi/
 100         xscreensaver/res/drawable/
 101
 102     Files that we generate:
 103
 104         gen/function-table.h
 105         xscreensaver/AndroidManifest.xml
 106         xscreensaver/res/drawable/*.png
 107         xscreensaver/res/values/settings.xml
 108         xscreensaver/res/values/strings.xml
 109         xscreensaver/res/xml/*.xml
 110         xscreensaver/src/org/jwz/xscreensaver/gen/*.java
 111
 112     Other files generated as a part of the build process:
 113
 114         gen/
 115         .gradle/
 116         xscreensaver/build/
 117         xscreensaver/build/outputs/apk/  -- app appears here
 118         xscreensaver/jni/
 119         xscreensaver/libs/
 120         xscreensaver/obj/
 121         xscreensaver/res/
 122         xscreensaver/res/drawable/
 123         xscreensaver/res/values/
 124         xscreensaver/res/xml/
 125         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   antinspect    crashes emulator, sometimes
 154   antmaze       crashes emulator, sometimes
 155   antspotlight  crashes emulator, sometimes
 156   apple2        text, images into pixmaps doesn't work
 157   atlantis      crashes emulator, sometimes
 158   barcode       pixmaps
 159   binaryring    pixmaps
 160   blitspin      images
 161   bouboule      ?
 162   bsod          pixmaps, XCopyArea problems
 163   bumps         XPutImage
 164   carousel      blank
 165   circuit       crashes emulator
 166   cityflow      crashes emulator, sometimes
 167   crackberg     crashes emulator, sometimes
 168   cube21        crashes emulator, sometimes
 169   cubenetic     crashes emulator, sometimes
 170   cubicgrid     crashes emulator, sometimes
 171   dnalogo       codeword is blank
 172   dymaxionmap   crashes emulator
 173   endgame       crashes emulator
 174   engine        text
 175   esper         text
 176   flipflop      images
 177   flipscreen3d  images
 178   fliptext      text
 179   fontglide     text
 180   gflux         images
 181   glblur        crashes emulator, sometimes
 182   gleidescope   images
 183   glhanoi       crashes emulator, but a few seconds in
 184   glplanet      crashes emulator
 185   glslideshow   images
 186   halftone      XFillArc crash
 187   halo          XOR
 188   hypertorus    crashes emulator
 189   interaggregate        window background should be white
 190   jigglypuff    incredibly slow
 191   jigsaw        crashes emulator
 192   juggler3d     crashes emulator
 193   maze          no logo, lines look weird
 194   mirrorblob    images
 195   moebius       crashes emulator
 196   moire2        pixmaps
 197   molecule      crashes emulator
 198   mountain      polygons
 199   munch         XOR
 200   noseguy       pixmaps
 201   pacman        launches really slowly
 202   pedal         polygons
 203   phosphor      pixmaps
 204   photopile     pixmaps
 205   pipes         blank
 206   polyhedra     crashes emulator
 207   polyominoes   pixmaps
 208   projectiveplane       crashes emulator
 209   pulsar        crashes emulator
 210   qix           polygons
 211   queens        crashes emulator
 212   skytentacles  crashes emulator
 213   slip          pixmaps
 214   sonar         crashes emulator
 215   speedmine     polygons
 216   spheremonics  crashes emulator
 217   splitflap     text
 218   spotlight     pixmaps
 219   starfish      polygons
 220   starwars      crashes emulator
 221   substrate     background should be white
 222   surfaces      crashes emulator
 223   tessellimage  pixmaps
 224   twang         background should be black
 225   unicrud       pixmaps
 226   xanalogtv     pixmaps
 227   xjack         blank
 228   xmatrix       pixmaps
 229   zoom          pixmaps