# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Android SDL display: Activity orientation from logical aspect, surface scale.
MCU-shaped contract: the app chooses orientation via panel size / ``rotation``
(logical ``width`` vs ``height``). The Activity is locked to that aspect;
tilting the phone does not change it — the user turns the device to match.
"""
from __future__ import annotations
import sys
import time
import usdl2
from displaydev.sdldisplay import SDLDisplay, retcheck
import keys
__all__ = ["AndroidSDLDisplay"]
# android.content.pm.ActivityInfo
_ORIENTATION_LANDSCAPE = 0
_ORIENTATION_PORTRAIT = 1
_HINT_ORIENTATIONS = getattr(usdl2, "SDL_HINT_ORIENTATIONS", "SDL_IOS_ORIENTATIONS")
def _logical_size(width, height, rotation):
"""Return logical (w, h) for stored panel size + rotation degrees."""
rot = int(rotation) % 360
if ((rot // 90) & 0x1) == 0x1:
return int(height), int(width)
return int(width), int(height)
def _set_orientation_hint(landscape):
"""Restrict SDL Android orientations to the locked aspect."""
set_hint = getattr(usdl2, "SDL_SetHint", None)
if set_hint is None:
return
value = "LandscapeLeft LandscapeRight" if landscape else "Portrait"
try:
set_hint(_HINT_ORIENTATIONS, value)
except Exception:
pass
def _set_activity_orientation(landscape):
"""Lock the Activity to fixed landscape or portrait (not SENSOR_*)."""
if sys.platform != "android":
return
try:
from jnius import autoclass
except ImportError:
return
try:
PythonActivity = autoclass("org.kivy.android.PythonActivity")
activity = PythonActivity.mActivity
if activity is None:
return
flag = _ORIENTATION_LANDSCAPE if landscape else _ORIENTATION_PORTRAIT
activity.setRequestedOrientation(flag)
except Exception:
pass
def _activity_views():
"""The Activity's decor view and SDL's SurfaceView, or ``[]`` off-Android."""
if sys.platform != "android":
return []
try:
from jnius import autoclass
except ImportError:
return []
try:
activity = autoclass("org.kivy.android.PythonActivity").mActivity
if activity is None:
return []
views = [activity.getWindow().getDecorView()]
surface = autoclass("org.libsdl.app.SDLActivity").mSurface
if surface is not None:
views.append(surface)
return views
except Exception:
return []
def _wait_activity_shape(landscape, timeout_s=3.0, settled=5, poll_s=0.02):
"""Wait for the Activity's views to take the locked shape, before CreateWindow.
``setRequestedOrientation`` returns at once and the turn happens later.
An SDL window and renderer created while the Activity is still turning
can draw a frame that never reaches the screen, and an app that draws
once and waits for input then stays black. Waiting until the decor view
and SDL's surface have the new shape, unchanged for ``settled`` polls,
gives the renderer a settled surface to start on. When the Activity is
already in that orientation this costs ``settled`` polls (about 0.1 s).
"""
views = _activity_views()
if not views:
return False
def shapes():
try:
return tuple((int(v.getWidth()), int(v.getHeight())) for v in views)
except Exception:
return None
deadline = time.monotonic() + float(timeout_s)
last = None
stable = 0
while time.monotonic() < deadline:
now = shapes()
if (
now is not None
and now == last
and all(w > 0 and h > 0 and (w > h) == landscape for w, h in now)
):
stable += 1
if stable >= settled:
return True
else:
stable = 0
last = now
time.sleep(poll_s)
return False
def _android_surface_sizes():
"""``(dm_wh, decor_wh)`` from the Activity, or ``(None, None)`` off-Android."""
if sys.platform != "android":
return None, None
try:
from jnius import autoclass
except ImportError:
return None, None
try:
PythonActivity = autoclass("org.kivy.android.PythonActivity")
activity = PythonActivity.mActivity
if activity is None:
return None, None
dm = activity.getResources().getDisplayMetrics()
dm_wh = (int(dm.widthPixels), int(dm.heightPixels))
if dm_wh[0] <= 0 or dm_wh[1] <= 0:
dm_wh = None
decor = activity.getWindow().getDecorView()
decor_wh = (int(decor.getWidth()), int(decor.getHeight()))
if decor_wh[0] <= 0 or decor_wh[1] <= 0:
decor_wh = None
return dm_wh, decor_wh
except Exception:
return None, None
def _pump_sdl(limit=64):
"""Drain SDL events so the Android video backend can apply surface resizes."""
pump = getattr(usdl2, "SDL_PumpEvents", None)
if pump is not None:
try:
pump()
except Exception:
pass
event = usdl2.SDL_Event()
for _ in range(limit):
try:
if not usdl2.SDL_PollEvent(event):
break
except Exception:
break
def _sdl_output_size(window, renderer):
"""Best-effort SDL drawable size after an Android surface change."""
get_out = getattr(usdl2, "SDL_GetRendererOutputSize", None)
if get_out is not None and renderer is not None:
try:
size = get_out(renderer)
if size and size[0] > 0 and size[1] > 0:
return int(size[0]), int(size[1])
except Exception:
pass
get_win = getattr(usdl2, "SDL_GetWindowSize", None)
if get_win is not None and window is not None:
try:
size = get_win(window)
if size and size[0] > 0 and size[1] > 0:
return int(size[0]), int(size[1])
except Exception:
pass
return None
def _aspect_ok(size, landscape):
if size is None:
return False
w, h = size
if landscape:
return w > h
return h >= w
def _wait_drawable_aspect(window, renderer, landscape, timeout_s=2.5):
"""Wait until SDL drawable aspect matches the locked Activity orientation.
Non-fullscreen Android windows often settle to a short landscape size (e.g.
``2282x880`` while decor is ``2282x1080``) and never match decor — do not
block on pixel alignment. Do **not** call ``SDL_SetWindowSize``.
"""
deadline = time.time() + float(timeout_s)
last_dm, last_decor = _android_surface_sizes()
last_sdl = _sdl_output_size(window, renderer)
stable = None
stable_n = 0
while time.time() < deadline:
_pump_sdl()
dm, decor = _android_surface_sizes()
last_dm = dm or last_dm
last_decor = decor or last_decor
last_sdl = _sdl_output_size(window, renderer) or last_sdl
if _aspect_ok(last_sdl, landscape) and (last_dm is None or _aspect_ok(last_dm, landscape)):
if last_sdl == stable:
stable_n += 1
if stable_n >= 5:
return last_sdl
else:
stable = last_sdl
stable_n = 1
time.sleep(0.02)
return last_sdl or last_decor or last_dm
[docs]
class AndroidSDLDisplay(SDLDisplay):
"""``SDLDisplay`` for Android: aspect → Activity lock, no RenderCopyEx rotate."""
quit_chord = (keys.K_AC_BACK, 0)
def __init__(
self,
width=320,
height=240,
rotation=0,
color_depth=16,
title="SDL2 Display",
scale=1.0,
window_flags=usdl2.SDL_WINDOW_SHOWN,
render_flags=usdl2.SDL_RENDERER_ACCELERATED | usdl2.SDL_RENDERER_PRESENTVSYNC,
x=usdl2.SDL_WINDOWPOS_CENTERED,
y=usdl2.SDL_WINDOWPOS_CENTERED,
*,
quiet=False,
):
lw, lh = _logical_size(width, height, rotation)
landscape = lw > lh
_set_orientation_hint(landscape)
# Lock before CreateWindow, and let the turn finish, so the window and
# renderer start on a surface that already has the locked shape.
_set_activity_orientation(landscape)
_wait_activity_shape(landscape)
# scale=1: CreateWindow uses logical panel size, not desktop scale.
# _fit_scale below keeps it there.
super().__init__(
width=width,
height=height,
rotation=rotation,
color_depth=color_depth,
title=title,
scale=1.0,
window_flags=window_flags,
render_flags=render_flags,
x=x,
y=y,
quiet=quiet,
)
# Requested scale kept for API/recorder; Android window sizing ignores it.
self._scale = 1.0 if scale <= 0 else float(scale)
self._orient_settle_until = 0.0
self._await_drawable(landscape)
def _fit_scale(self, desktop_w, desktop_h, quiet):
"""Do not let board_config scale drive CreateWindow on Android.
A portrait ``720x1280`` at ``scale=2`` becomes ``1440x2560``. After a WIDE
Activity lock, SDL still letterboxes into that stale tall size and content
clips to the top-left. Window size follows the Activity SurfaceView; logical
panel size is applied with ``RenderSetLogicalSize``.
"""
del desktop_w, desktop_h, quiet
return 1.0
def _await_drawable(self, landscape=None):
"""Pump until the SurfaceView/SDL drawable matches the locked aspect."""
if sys.platform != "android":
return
if landscape is None:
landscape = int(self.width) > int(self.height)
_wait_drawable_aspect(
getattr(self, "_window", None),
getattr(self, "_renderer", None),
landscape,
)
def _mark_orient_settle(self):
"""After Activity orientation, force recomposite until EGL presents stick.
Non-fullscreen surfaces report the new size quickly, but the first
``RenderPresent`` calls are dropped; ``needs_refresh`` Present-only ticks
then keep showing a black backbuffer. Re-running ``render()`` for a short
window recovers.
"""
self._orient_settle_until = time.time() + 2.5
self._render_dirty = True
[docs]
def show(self, _timer=None) -> None:
if time.time() < float(getattr(self, "_orient_settle_until", 0) or 0):
self._render_dirty = True
super().show(_timer)
def _rebind_logical_texture(self, tex_w, tex_h):
"""Swap the target texture + logical size; keep the existing renderer.
Non-fullscreen landscape drawables often stay at a short size.
Destroying/recreating the renderer there blacks out presents;
``RenderSetLogicalSize`` + a new texture on the live renderer is enough.
"""
old_tex = getattr(self, "_buffer", None)
renderer = getattr(self, "_renderer", None)
if renderer is None:
raise RuntimeError("AndroidSDLDisplay: no renderer")
if old_tex is not None:
try:
usdl2.SDL_DestroyTexture(old_tex)
except Exception:
pass
self._buffer = None
texture = usdl2.SDL_CreateTexture(
renderer,
self._px_format,
usdl2.SDL_TEXTUREACCESS_TARGET,
int(tex_w),
int(tex_h),
)
if not texture:
raise RuntimeError("%s" % (usdl2.SDL_GetError(),))
retcheck(usdl2.SDL_SetTextureBlendMode(texture, usdl2.SDL_BLENDMODE_NONE))
retcheck(usdl2.SDL_RenderSetLogicalSize(renderer, int(tex_w), int(tex_h)))
self._buffer = texture
self._render_dirty = True
[docs]
def init(self) -> None:
"""Wait for drawable aspect, then apply MCU logical size for letterboxing."""
self._await_drawable()
super().init()
def _apply_activity_orientation(self, width=None, height=None):
"""Lock Activity to logical aspect (``width > height`` → landscape)."""
w = int(self.width if width is None else width)
h = int(self.height if height is None else height)
landscape = w > h
_set_orientation_hint(landscape)
_set_activity_orientation(landscape)
self._await_drawable(landscape)
def _rotation_helper(self, value):
"""Lock Activity to the new aspect; rebind logical texture (no RenderCopyEx).
Phone orientation carries the aspect (MCU-shaped). Does not require
fullscreen — non-FS landscape SDL size may be shorter than decor.
"""
angle = (value % 360) - (self._rotation % 360)
if angle == 0:
return
if abs(angle) % 180 == 0:
new_w, new_h = self.width, self.height
else:
new_w, new_h = self.height, self.width
self._apply_activity_orientation(new_w, new_h)
self._rebind_logical_texture(new_w, new_h)
self._mark_orient_settle()