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    renders incorrectly
 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   blitspin      images
 160   bsod          pixmaps, XCopyArea problems
 161   bumps         images
 162   carousel      images
 163   cityflow      shading is wrong
 164   endgame       insanely slow
 165   engine        text
 166   esper         images, text
 167   flipflop      images
 168   flipscreen3d  images
 169   fliptext      text
 170   fontglide     text
 171   gflux         images
 172   glblur        grayscale instead of color
 173   gleidescope   images
 174   glslideshow   images
 175   halftone      XFillArc crash
 176   halo          some extra triangles show up
 177   jigglypuff    incredibly slow
 178   jigsaw        images
 179   juggler3d     blank
 180   maze          lines are not the same thickness (aliased?)
 181   mirrorblob    images
 182   molecule      blank
 183   mountain      polygons
 184   munch         XOR
 185   noseguy       text; images flicker to black and white
 186   pacman        launches really slowly
 187   pedal         polygons
 188   phosphor      text; pixmaps
 189   photopile     images; pixmaps
 190   polyhedra     text
 191   polyominoes   pixmaps
 192   qix           polygons
 193   queens        blank
 194   slip          images
 195   sonar         does icmp work?
 196   speedmine     polygons
 197   splitflap     super slow
 198   spotlight     pixmaps
 199   starfish      polygons
 200   starwars      text
 201   tessellimage  pixmaps
 202   twang         background should be black
 203   unicrud       pixmaps
 204   winduprobot   dome is not transparent
 205   xanalogtv     pixmaps
 206   xflame        draws only upper left corner
 207   xmatrix       super slow, glitch on first screen
 208   zoom          pixmaps