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   apple2        text, images into pixmaps doesn't work
 155   barcode       pixmaps
 156   bsod          pixmaps, XCopyArea problems
 157   carousel      images are corrupted
 158   cityflow      shading is wrong
 159   endgame       insanely slow
 160   engine        text
 161   esper         images don't load, no text
 162   fliptext      text
 163   fontglide     text
 164   glblur        grayscale instead of color
 165   halftone      XFillArc crash
 166   jigglypuff    incredibly slow
 167   juggler3d     blank
 168   maze          lines are not the same thickness (aliased?)
 169   molecule      blank
 170   noseguy       text; images
 171   pacman        images; launches really slowly
 172   pedal         polygons
 173   phosphor      text; pixmaps
 174   photopile     text; images don't display
 175   polyhedra     text
 176   polyominoes   pixmaps
 177   qix           polygons
 178   queens        insanely slow
 179   sonar         does icmp work?
 180   speedmine     polygons
 181   splitflap     super slow
 182   spotlight     blank
 183   starfish      polygons
 184   starwars      text
 185   unicrud       pixmaps
 186   winduprobot   dome is not transparent
 187   xanalogtv     pixmaps
 188   xflame        draws only upper left corner
 189   xmatrix       pretty slow