Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,3 +137,47 @@ devices.
firmware, e.g. HiBreak Plus). Reflective; no permission needed.
- **Onyx**: requires the Boox vendor SDK runtime. The class load succeeds on
any device but `attach` throws on non-Onyx and we return false.

## Optional standard Android controller

`InkControllerFactory.createStandard()` provides a public-API stylus implementation
for tablets without a vendor overlay. It is opt-in: `create()` still selects the
existing Bigme/Onyx implementations, and `createNoop()` is unchanged. This path uses
ordinary SurfaceView composition and makes no hardware-overlay latency guarantee.

```kotlin
val ink = InkControllerFactory.createStandard()
// Call from SurfaceHolder.Callback after layout, when the surface is valid.
ink.attach(surfaceView, Rect(0, 0, surfaceView.width, surfaceView.height), callback)
ink.setStrokeStyle(widthPx = 5f, color = Color.BLACK)
// Supply the authoritative page before writing and after host document edits.
ink.syncOverlay(pageBitmap)
```

The controller installs an OnTouchListener on the attached SurfaceView. Do not
also forward the same events manually. NativeActivity hosts that bypass View
dispatch may instead call `onMotionEvent` once per event. Input, presentation and
configuration belong on the main thread. Detach before the surface is destroyed.
The host owns document persistence, undo, scrolling and eraser behavior.

- Stylus input is captured; finger and eraser contacts are not consumed. This does
not itself dispatch touches to sibling views: the host chooses their routing.
- Coalesced historical points are delivered in order. Presentations are batched
per MotionEvent, including the final UP segment.
- Writing bounds and exclusions prevent control contacts from becoming ink.
`setExcludedPenTouch` can route excluded pen contacts to host controls.
- `setCaptureOnly` or `setCaptureOnlyAt` delivers gestures without painting them,
allowing host-owned selection, checkboxes and erasing without a temporary dot.
- `syncOverlay` replaces authoritative pixels, including transparent pixels;
`syncChrome` updates a cropped control area without clearing the page.
- Call `setEnabled(false)` before host redraws. The current stroke is completed
once. Size changes require reattachment and a fresh authoritative bitmap.
- Recorded timings are handler/draw/presentation-call durations, not measured
kernel-to-panel latency. Unit tests do not establish palm rejection or e-ink
refresh behavior; device acceptance remains necessary.

This contribution is adapted from [Kalamos InkSDK](https://github.com/josephm1/kalamos-inksdk),
which builds on **InkSDK by Ed Wei (imedwei) and contributors**. The new standard
controller, editing interface and their test are contributed under GPL-3.0-only;
see [docs/standard-android-NOTICE.md](docs/standard-android-NOTICE.md). Existing
upstream files retain their authorship and licensing status.
674 changes: 674 additions & 0 deletions docs/licenses/GPL-3.0-only.txt

Large diffs are not rendered by default.

15 changes: 15 additions & 0 deletions docs/standard-android-NOTICE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Standard Android contribution

The new `StandardInkController.kt`, `InkEditingController.kt` and
`StandardInkEditingTest.kt` are adapted from the Kalamos InkSDK adaptation by
josephm1 and contributed under **GPL-3.0-only**. The complete licence is in
[GPL-3.0-only.txt](licenses/GPL-3.0-only.txt).

Kalamos InkSDK builds on **[InkSDK](https://github.com/imedwei/inksdk) by Ed Wei
(imedwei) and contributors**, whose original authorship and credit are preserved.
The pressure/dash helpers and opt-in factory entry accompany this contribution.
This notice does not relicense existing upstream files or third-party libraries.

Source: https://github.com/josephm1/kalamos-inksdk at
b316946d67013a457170c15664c882e6d628561d. The implementation is adapted to the
upstream package/API, with final-UP presentation and disjoint-region guards.
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ object InkControllerFactory {
if (BigmeInkController.isBigmeDevice()) BigmeInkController()
else OnyxInkController()

/** Opt-in public Android stylus path; vendor auto-selection remains unchanged. */
fun createStandard(): InkEditingController = StandardInkController()

fun createNoop(): InkController = NoopInkController

/** True iff the current device is identified as a Bigme device. */
Expand Down
7 changes: 7 additions & 0 deletions inkcontroller/src/main/java/com/inksdk/ink/InkDefaults.kt
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,11 @@ import android.graphics.Color
object InkDefaults {
const val DEFAULT_STROKE_WIDTH_PX: Float = 5f
const val DEFAULT_STROKE_COLOR: Int = Color.BLACK

/** Shared live/replay pressure curve: 0.3x to 2x of the base width. */
fun pressureToWidth(baseWidthPx: Float, pressure: Float): Float =
baseWidthPx * (0.3f + 1.7f * pressure.coerceIn(0f, 1f))

/** Surface-pixel dash pattern for selection trails. */
fun dashIntervals(): FloatArray = floatArrayOf(16f, 24f)
}
36 changes: 36 additions & 0 deletions inkcontroller/src/main/java/com/inksdk/ink/InkEditingController.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
// SPDX-License-Identifier: GPL-3.0-only
// Adapted from Kalamos InkSDK by josephm1; builds on InkSDK by Ed Wei and contributors.
package com.inksdk.ink

import android.graphics.Bitmap
import android.graphics.Rect

/** Optional native editing capabilities shared by reader hosts; no document or vendor policy. */
interface InkEditingController : InkController {
/** Input clipping and pen presentation options; all coordinates are view-local pixels. */
fun setWritingTop(topPx: Int)
fun setWritingExclusion(left: Int, top: Int, right: Int, bottom: Int)
fun setWritingBounds(left: Int, top: Int, right: Int, bottom: Int)
/** Leave eraser gestures to the host instead of painting ink. */
fun setEraserMode(active: Boolean)
fun setPressureMode(active: Boolean)
fun setDashMode(active: Boolean)
/** Ordinary surface presentation; no vendor fast-waveform claim. */
fun refreshRegionFast(bitmap: Bitmap, region: Rect) = syncOverlay(bitmap, region)

val isAvailable: Boolean get() = true
/** NativeActivity hosts must forward their raw input queue; normal View hosts do not. */
val requiresMotionForwarding: Boolean get() = false
fun onMotionEvent(event: android.view.MotionEvent): Boolean = false
/** Deliver gestures without drawing their temporary trail (eraser/selection manipulation). */
fun setCaptureOnly(active: Boolean)
/** Decide capture-only ownership at DOWN, before painting the first sample. */
fun setCaptureOnlyAt(decision: ((Float, Float) -> Boolean)?)
/** Optional daemon visibility; ordinary Android already uses the host's surface. */
fun setOverlayVisible(visible: Boolean) {}
/** Excluded control contacts must not become saved strokes. Action uses MotionEvent constants. */
fun setExcludedPenTouch(listener: ((Int, Float, Float) -> Unit)?)
/** A cropped chrome bitmap at region's surface-local origin; preserve all other pixels. */
fun syncChrome(bitmap: Bitmap, region: Rect)
fun syncOverlayRubber(bitmap: Bitmap, region: Rect) = syncOverlay(bitmap, region, true)
}
Loading