Skip to content

Commit 448fad9

Browse files
titotito
committed
add api for android/android_mixer (taken from pgs4a)
1 parent 6a72910 commit 448fad9

File tree

1 file changed

+113
-4
lines changed

1 file changed

+113
-4
lines changed

‎docs/source/android.rst

Lines changed: 113 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,16 @@ Example
1919
How it's working
2020
----------------
2121

22-
The whole Android API is accessible in Java. Their is no native or extensible way to access it from Python. The schema for accessing to their API is:
22+
The whole Android API is accessible in Java. Their is no native or extensible way to access it from Python. The schema for accessing to their API is::
2323

2424
[1] Cython -> [2] C JNI -> [3] Java
2525

26-
#. The ``android.pyx`` is written in Cython: a language with typed informations, very close to Python, that generate Python extension. It's easier to write in Cython than CPython, and it's linked directly to the part 2.
27-
#. The second part define simple c methods that access to Java interfaces through JNI in the file ``android_jni.c``.
26+
#. ``android.pyx`` is written in `Cython <http://cython.org/>`_: a language
27+
with typed informations, very close to Python, that generate Python
28+
extension. It's easier to write in Cython than CPython, and it's linked
29+
directly to the part 2.
30+
#. ``android_jni.c`` is defining simple c methods that access to Java
31+
interfaces using JNI layer.
2832
#. The last part contain the Java code that will be called from the JNI stuff.
2933

3034
All the source code is available at:
@@ -35,4 +39,109 @@ All the source code is available at:
3539
API
3640
---
3741

38-
TODO
42+
android
43+
~~~~~~~
44+
45+
.. module:: android
46+
47+
.. function:: check_pause()
48+
49+
This should be called on a regular basis to check to see if Android
50+
expects the game to pause. If it return true, the game should
51+
call :func:`android.wait_for_resume()`, after persisting its state
52+
as necessary.
53+
54+
.. function:: wait_for_resume()
55+
56+
This function should be called after :func:`android.check_pause()`
57+
returns true. It does not return until Android has resumed from
58+
the pause. While in this function, Android may kill a game
59+
without further notice.
60+
61+
.. function:: map_key(keycode, keysym)
62+
63+
This maps between an android keycode and a python keysym. The android
64+
keycodes are available as constants in the android module.
65+
66+
.. function:: vibrate(s)
67+
68+
Causes the phone to vibrate for `s` seconds. This requires that your
69+
application have the VIBRATE permission.
70+
71+
.. function:: accelerometer_enable(enable)
72+
73+
Enables (if `enable` is true) or disables the device's accelerometer.
74+
75+
.. function:: accelerometer_reading()
76+
77+
Returns an (x, y, z) tuple of floats that gives the accelerometer
78+
reading, in meters per second squared. See `this page
79+
<http://developer.android.com/reference/android/hardware/SensorEvent.html>`_
80+
for a description of the coordinate system. The accelerometer must
81+
be enabled before this function is called. If the tuple contains
82+
three zero values, the accelerometer is not enabled, not available,
83+
defective, has not returned a reading, or the device is in
84+
free-fall.
85+
86+
.. function:: get_dpi()
87+
88+
Returns the screen density in dots per inch.
89+
90+
.. function:: show_keyboard()
91+
92+
Shows the soft keyboard.
93+
94+
.. function:: hide_keyboard()
95+
96+
Hides the soft keyboard.
97+
98+
android_mixer
99+
~~~~~~~~~~~~~
100+
101+
.. module:: android_mixer
102+
103+
The android_mixer module contains a subset of the functionality in found
104+
in the `pygame.mixer <http://www.pygame.org/docs/ref/mixer.html>`_ module. It's
105+
intended to be imported as an alternative to pygame.mixer, using code like: ::
106+
107+
try:
108+
import pygame.mixer as mixer
109+
except ImportError:
110+
import android_mixer as mixer
111+
112+
Note that if you're using `kivy.core.audio
113+
<http://kivy.org/docs/api-kivy.core.audio.html>`_ module, you don't have to do
114+
anything, all is automatic.
115+
116+
The android_mixer module is a wrapper around the Android MediaPlayer
117+
class. This allows it to take advantage of any hardware acceleration
118+
present, and also eliminates the need to ship codecs as part of an
119+
application.
120+
121+
It has several differences from the pygame mixer:
122+
123+
* The init and pre_init methods work, but are ignored - Android chooses
124+
appropriate setting automatically.
125+
126+
* Only filenames and true file objects can be used - file-like objects
127+
will probably not work.
128+
129+
* Fadeout does not work - it causes a stop to occur.
130+
131+
* Looping is all or nothing, there's no way to choose the number of
132+
loops that occur. For looping to work, the
133+
:func:`android_mixer.periodic` function should be called on a
134+
regular basis.
135+
136+
* Volume control is ignored.
137+
138+
* End events are not implemented.
139+
140+
* The mixer.music object is a class (with static methods on it),
141+
rather than a module. Calling methods like :func:`mixer.music.play`
142+
should work.
143+
144+
.. note::
145+
146+
The android_mixer module hasn't been tested much, and so bugs may be
147+
present.

0 commit comments

Comments
 (0)