Skip to content

Commit 03d823d

Browse files
xaionaro@dx.centerxaionaro@dx.center
authored andcommitted
docs: add Interoperability section to README with gomobile example
1 parent 08a1dcc commit 03d823d

File tree

1 file changed

+82
-0
lines changed

1 file changed

+82
-0
lines changed

README.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1627,6 +1627,88 @@ bridging. Writing CGo from scratch duplicates this work and lacks the
16271627
automated test coverage this project maintains.
16281628
-->
16291629
1630+
## Interoperability with standard packages
1631+
1632+
All handle types expose `UintPtr() uintptr` and `NewXFromUintPtr(uintptr)` methods alongside the existing `Pointer()`/`NewXFromPointer()` pair. This enables interop with Go packages that represent native Android handles as `uintptr` — including `golang.org/x/mobile`, `gioui.org`, and `github.com/xlab/android-go`.
1633+
1634+
For generic code, all handles satisfy the `handle.NativeHandle` interface:
1635+
1636+
```go
1637+
import "github.com/AndroidGoLab/ndk/handle"
1638+
1639+
func logHandle(h handle.NativeHandle) {
1640+
log.Printf("native handle: 0x%x", h.UintPtr())
1641+
}
1642+
```
1643+
1644+
EGL types (`EGLDisplay`, `EGLContext`, etc.) are `unsafe.Pointer` aliases and use free functions instead: `egl.EGLDisplayToUintPtr(d)` / `egl.EGLDisplayFromUintPtr(p)`.
1645+
1646+
<details>
1647+
<summary>gomobile bind</summary>
1648+
1649+
`gomobile bind` does not support `unsafe.Pointer` or `uintptr` in exported APIs. Transport native handles as `int64` (Java `long`) and convert inside Go:
1650+
1651+
```go
1652+
package sensorbridge
1653+
1654+
import "github.com/AndroidGoLab/ndk/sensor"
1655+
1656+
// Bridge wraps an ASensorManager for cross-language use.
1657+
// Unexported fields are invisible to Java/Kotlin.
1658+
type Bridge struct {
1659+
mgr *sensor.Manager
1660+
}
1661+
1662+
// NewBridge creates a Bridge from a raw ASensorManager* passed as int64
1663+
// (Java long). gomobile bind does not support unsafe.Pointer or uintptr,
1664+
// so native handles must be transported as int64.
1665+
func NewBridge(managerHandle int64) *Bridge {
1666+
return &Bridge{
1667+
mgr: sensor.NewManagerFromUintPtr(uintptr(managerHandle)),
1668+
}
1669+
}
1670+
1671+
// Handle returns the underlying ASensorManager* as int64 for passing
1672+
// back to Java/JNI code.
1673+
func (b *Bridge) Handle() int64 {
1674+
return int64(b.mgr.UintPtr())
1675+
}
1676+
1677+
// AccelerometerName returns the name of the default accelerometer,
1678+
// or empty string if unavailable.
1679+
func (b *Bridge) AccelerometerName() string {
1680+
s := b.mgr.DefaultSensor(sensor.Accelerometer)
1681+
if s.UintPtr() == 0 {
1682+
return ""
1683+
}
1684+
return s.Name()
1685+
}
1686+
1687+
// SensorName returns the name of a sensor by its Android type code,
1688+
// or empty string if the sensor is not available.
1689+
func (b *Bridge) SensorName(sensorType int32) string {
1690+
s := b.mgr.DefaultSensor(sensor.Type(sensorType))
1691+
if s.UintPtr() == 0 {
1692+
return ""
1693+
}
1694+
return s.Name()
1695+
}
1696+
```
1697+
1698+
Build AAR: `gomobile bind -target=android -androidapi=35 ./examples/gomobile/sensorbridge`
1699+
1700+
Java usage:
1701+
1702+
```java
1703+
long ptr = nativeGetSensorManager(); // from JNI
1704+
Bridge bridge = Sensorbridge.newBridge(ptr);
1705+
String name = bridge.accelerometerName();
1706+
```
1707+
1708+
See [`examples/gomobile/sensorbridge/`](examples/gomobile/sensorbridge/) for the complete buildable example.
1709+
1710+
</details>
1711+
16301712
## FAQ
16311713

16321714
**Q: Why NativeActivity instead of GameActivity?**

0 commit comments

Comments
 (0)