D Donkeh docs
GitHub

Android

Donkeh.Windowing.Android is deliberately small. It is the framework-owned Android activity that boots the portable windowing stack on an external GLES surface, applies mobile defaults, translates display density into CSS pixels, and installs the Android runtime-permission provider. App code still declares only an [AppRoot].

What the package hides

The application project targets net10.0-android and references this package, but never writes an activity. The host hides four things that would otherwise leak into every app:

ConcernHandled by
Launcher activity and manifest entryDonkehActivity is the MainLauncher, exported, with a fullscreen no-action-bar theme.
GLES context and surfaceCreates a Silk.NET view with OpenGL ES 3.0, depth 24, stencil 8, no MSAA, VSync and a 60 Hz cap.
Density and lifecycleReads display density, converts the external surface into a CSS-pixel viewport and keeps the activity across configuration changes.
Runtime permissionsInstalls an IPermissionService that requests from the activity and completes from OnRequestPermissionsResult.

The activity

DonkehActivity derives from Silk.NET's SDL-backed SilkActivity. Its attributes declare a fullscreen Material no-action-bar theme and a configuration-change set that includes orientation, keyboard, UI mode, density, screen layout and smallest screen size. Because the activity handles those changes itself, rotation does not recreate it: the same DonkehWindow keeps running and CSS reflows against the new surface size.

[Activity(
    Label = "Donkeh",
    MainLauncher = true,
    Exported = true,
    Theme = "@android:style/Theme.Material.NoActionBar.Fullscreen",
    ConfigurationChanges = SilkActivity.ConfigChangesFlags
        | ConfigChanges.UiMode
        | ConfigChanges.Density
        | ConfigChanges.ScreenLayout
        | ConfigChanges.SmallestScreenSize)]
public class DonkehActivity : SilkActivity

The SDL binding seam

SilkActivity is abstract, so .NET Android does not emit a static JNI registration block for it, and the delegate getters that register n_loadLibraries, n_setOrientationBis and n_onDestroy are private on the binding base. The host re-exposes those handlers for this concrete activity through GetBaseHandler, which reflects the private static getter once. DynamicDependency attributes keep the binding members rooted for trimming.

Reflection is confined to the binding seam This is one of the few places where the host reaches into private framework members. The dependency is deliberate: it keeps the app-facing activity concrete without duplicating SDL's JNI bootstrap, and a Silk.NET binding upgrade that renames a handler fails loudly with MissingMethodException.

Starting the app

OnRun is the Android equivalent of the desktop entry point:

  1. Discover the [AppRoot] definition.
  2. Read Resources.DisplayMetrics.Density.
  3. Create AndroidPermissionService and install it through Host.UsePermissions.
  4. Create a GLES 3.0 view with a 24-bit depth buffer, 8-bit stencil, no MSAA, VSync and a 60 FPS cap.
  5. Clone the app settings and override everything the activity owns: size, chrome, VSync, frame cap, samples, resizability, devtools and DPI.
  6. Create DonkehWindow, run the view with the app root and merged styles, and let the shared window loop do the rest.
var settings = app.Settings with
{
    Width = 0,                    // the activity owns the surface
    Height = 0,
    VSync = true,
    TargetFramesPerSecond = 60,
    Samples = 0,                  // no MSAA on the mobile path
    Resizable = false,
    Frameless = false,
    EnableDevTools = false,
    EnableTouchScrolling = true, // swipe pans the nearest scroll container
    DpiScale = density
};

An app’s requested window width, height, frame style, MSAA, drag-resize and devtools settings are therefore visual suggestions on Android, not contracts. The surface, frame pacing and chrome belong to the activity.

Density and CSS pixels

Android reports a surface in physical pixels and a density scalar, not a desktop-style logical window. The host passes density as WindowSettings.DpiScale, so the window divides view and pointer coordinates by it before layout and hit testing. CSS pixels stay independent of the panel resolution.

Some SDL builds already expose a logical window size and a larger drawable. In that case applying density again would shrink the UI, so the Loaded handler checks the ratio and resets DpiScale to zero when the framebuffer is already larger than the logical size. The same handler prints density, DPI, size, framebuffer and GL version for diagnosis.

Touch scrolling

SDL synthesizes mouse events from a single finger, which keeps taps, focus and app-owned pointer handlers working. The missing piece is panning, so the host enables EnableTouchScrolling: a drag over scrollable content waits for an eight-pixel slop threshold, locks to the gesture’s dominant axis and scrolls the nearest container that can move on that axis. Panning bypasses smooth-scroll easing so the content tracks the finger. A press that never crosses the threshold is replayed as a normal click.

Gestures that begin on a scrollbar, text control, range slider, button, link, media element or an element with a pointerdown handler keep their existing behaviour. Scrollbar tracks gain a twelve-pixel inward hit margin on touch hosts, and touching beside the thumb starts a drag instead of jumping the track.

Long press

A touch press held still for 500 ms becomes a contextmenu event, so Android gets the same menus as a desktop right-click. Drifting more than 10 px, starting a drag or starting a scroll pan cancels the candidate. Once it fires, the click that would normally follow the release is suppressed, so the menu does not also activate the item under the finger.

Runtime permissions

AndroidPermissionService translates Donkeh’s portable HostPermission values into Android manifest permissions:

Donkeh permissionAndroid permission(s)
CameraCAMERA
MicrophoneRECORD_AUDIO
LocationACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION
NotificationsPOST_NOTIFICATIONS on API 33+; pre-33 resolves true
PhotosREAD_MEDIA_IMAGES on API 33+, otherwise READ_EXTERNAL_STORAGE
StorageREAD_MEDIA_IMAGES on API 33+, otherwise read/write external storage
Contacts / CalendarREAD_CONTACTS / READ_CALENDAR
BluetoothBLUETOOTH_CONNECT on API 31+, otherwise legacy BLUETOOTH
MotionACTIVITY_RECOGNITION on API 29+, otherwise unsupported
ClipboardResolves immediately; no runtime prompt

The provider first checks CheckSelfPermission for every required name and returns immediately when all are granted. Otherwise it allocates a request code, stores a pending completion in a dictionary, registers cancellation, and posts RequestPermissions to the UI thread. The activity forwards OnRequestPermissionsResult back to the provider, which completes the task and removes the entry.

Any-of versus all-of For a permission that maps to multiple Android names, the current result handler completes true when any requested name is granted. Location and pre-33 storage are the practical cases. Treat the portable boolean as “the platform granted enough to proceed”, not as proof that every manifest entry was accepted.

OnDestroy calls CancelAll, so every pending prompt resolves false when the activity closes. The app must still declare the matching uses-permission entries; the framework’s Android permission targets can emit them from the central DonkehAndroidPermissions list, and a hand-written manifest can add more.

INTERNET is added automatically when an app stylesheet references an external asset. The native host resolves remote @import rules, their @font-face sources and url(...) backgrounds at start-up; the build scans the app’s CSS for http:// or https:// and emits the permission. This matters for release builds because only debuggable APKs receive INTERNET implicitly from the Android SDK. Set DonkehAndroidInternet to true or false to override detection.

Android versus desktop

AreaAndroid behaviour
SurfaceActivity-owned GLES view; the app does not create a native desktop window.
Frame pacingVSync and a 60 FPS cap, regardless of desktop settings.
Chrome and resizeNo native title bar, frameless resize handles or window dragging.
MSAADisabled; the mobile path keeps the surface and bandwidth cost down.
DevtoolsDisabled by default on this path; the inspector is a desktop tool.
OrientationActivity configuration changes keep the instance; layout reflows on resize.
RendererGLES 3.0 through the same DonkehWindow, layout and GLRenderer pipeline.

Trade-offs and sharp edges

DecisionCost
Framework-owned activityZero app boilerplate, but the app cannot subclass or replace the launcher without writing its own host.
Reflection into SDL bindingsKeeps the JNI bootstrap working, but a binding rename is a compile-time-adjacent runtime failure.
Density with a fallbackCorrect CSS pixels on most devices, with a heuristic for SDL builds that already scale the view.
Any-of permission resultPractical for paired permissions, but cannot tell the app which individual name failed.
Fixed 60 Hz / no MSAAPredictable thermal and bandwidth behaviour, at the cost of high-refresh devices and smoother edges.
Manifest still app-ownedPermissions must be declared as well as requested; a missing manifest entry fails at runtime.
No devtools pathSaves layout and renderer overhead on mobile, but debugging happens on desktop or through logging.

Code tour

FileRead it for…
DonkehActivity.csActivity attributes, SDL handler seam, app discovery, GLES view setup, settings overrides and DPI fallback.
AndroidPermissionService.csPermission mapping, API-level differences, UI-thread request flow, pending completions and cancellation.
Donkeh.Windowing.Android.csprojThe net10.0-android target, minimum API and SDK path fallbacks.

The mental model: Android is not a separate UI stack. It is a thin activity adapter that owns the surface and permissions, then hands a GLES view to the same DonkehWindow used on desktop.