Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/godot-mobile-plugins/godot-native-camera

A Godot plugin that provides a unified camera capture interface for Android and iOS using native platform APIs.
https://github.com/godot-mobile-plugins/godot-native-camera

android godot godot-plugin ios mobile-camera

Last synced: 2 months ago
JSON representation

A Godot plugin that provides a unified camera capture interface for Android and iOS using native platform APIs.

Awesome Lists containing this project

README 

          



![](https://raw.githubusercontent.com/godot-mobile-plugins/godot-native-camera/main/demo/assets/native-camera-android.png)       ![](https://raw.githubusercontent.com/godot-mobile-plugins/godot-native-camera/main/demo/assets/native-camera-ios.png)








	

	

	

	








#  Godot Native Camera Plugin



A Godot plugin that provides a **unified camera capture interface** for **Android** and **iOS** using native platform APIs. It enables real‑time camera frame streaming directly into Godot with configurable resolution, rotation, frame skipping, horizontal/vertical mirroring, and optional grayscale output.



**Key Features:**



* Unified GDScript API for Android and iOS

* Enumerate available cameras and their supported output sizes

* Start and stop native camera frame streaming

* Receive raw frame buffers or ready‑to‑use `Image` objects

* Configurable resolution, rotation, frame skipping, horizontal/vertical mirroring, grayscale capture, and post-capture scaling

* **Auto-upright orientation correction** — automatically rotates every frame to be upright as the device is tilted, without any manual rotation tracking in your game code

* Designed for real‑time use cases (CV, AR preprocessing, custom rendering)



##  Table of Contents



* [Installation](#installation)

* [Usage](#usage)

* [Signals](#signals)

* [Methods](#methods)

* [Classes](#classes)

* [Platform-Specific Notes](#platform-specific-notes)

* [Links](#links)

* [All Plugins](#all-plugins)

* [Credits](#credits)

* [Contributing](#contributing)






##  Installation



*Before installing this plugin, make sure to uninstall any previous versions of the same plugin.*



*If installing both Android and iOS versions of the plugin in the same project, ensure that both versions use the same addon interface version.*



There are two ways to install the `NativeCamera` plugin into your project:



* Through the Godot Editor AssetLib

* Manually by downloading archives from GitHub



###  Installing via AssetLib



Steps:



* Search for **NativeCamera** in the Godot Editor AssetLib

* Click **Download**

* In the installation dialog:



  * Keep **Change Install Folder** set to your project root

  * Keep **Ignore asset root** checked

  * Click **Install**

* Enable the plugin from **Project → Project Settings → Plugins**



####  Installing both Android and iOS versions



When installing both platforms via AssetLib, Godot may warn that some files conflict and will not be installed. This is expected and safe to ignore, as both platforms share the same addon interface code.



###  Installing manually



Steps:



* Download the release archive from GitHub

* Unzip the archive

* Copy the contents into your Godot project root

* Enable the plugin via **Project → Project Settings → Plugins**






##  Usage



Add a `NativeCamera` node to your main scene or register it as an autoload (singleton).



Typical workflow:



1. Query available cameras using `get_cameras()`

2. Choose a camera and desired output size

3. Create a `FeedRequest` to configure the stream

4. Start the camera feed

5. Receive frames via signals



### Example



```gdscript

@onready var camera := $NativeCamera



func _ready():

	camera.camera_permission_granted.connect(_on_camera_permission_granted)

	camera.camera_permission_denied.connect(_on_camera_permission_denied)

	camera.frame_available.connect(_on_frame_available)

	camera.request_camera_permission()



func _on_camera_permission_granted() -> void:

	var cameras := camera.get_all_cameras()

	if cameras.is_empty():

		return



	var cam: CameraInfo = cameras[0]

	var request := FeedRequest.new()

		.set_camera_id(cam.get_camera_id())

		.set_width(1280)

		.set_height(720)

		.set_rotation(90)

		.set_grayscale(false)

		.set_mirror_horizontal(true)   # flip left-right (e.g. selfie camera preview)

		.set_mirror_vertical(false)

		.set_scale_width(640)          # downscale to 640×360 before emitting

		.set_scale_height(360)



	camera.start(request)



func _on_camera_permission_denied() -> void:

	push_error("Camera permission denied")



func _on_frame_available(frame: FrameInfo) -> void:

	var img := frame.get_image()

	# Use the image or raw buffer here

```



### Example with auto-upright



When `auto_upright` is enabled the plugin detects device orientation in real time and automatically applies the correct rotation to every frame. There is no need to set `rotation` manually or track orientation changes in your code.



```gdscript

@onready var camera := $NativeCamera



func _ready():

	camera.camera_permission_granted.connect(_on_camera_permission_granted)

	camera.frame_available.connect(_on_frame_available)

	camera.request_camera_permission()



func _on_camera_permission_granted() -> void:

	var cameras := camera.get_all_cameras()

	if cameras.is_empty():

		return



	var cam: CameraInfo = cameras[0]

	var request := FeedRequest.new()

		.set_camera_id(cam.get_camera_id())

		.set_width(1280)

		.set_height(720)

		.set_auto_upright(true)        # rotate frames automatically — no manual rotation needed



	camera.start(request)



func _on_frame_available(frame: FrameInfo) -> void:

	var img := frame.get_image()

	# img is always upright regardless of how the device is held

	# frame.get_rotation() reports the rotation that was applied

```



You can also set `auto_upright` through the Inspector by enabling the **Auto Upright** export property on the `NativeCamera` node and then calling `create_feed_request()`:



```gdscript

# In the Inspector, enable "Auto Upright" on the NativeCamera node, then:

var request := camera.create_feed_request()

camera.start(request)

```






##  Signals



Register listeners on the `NativeCamera` node:



* `camera_permission_granted()`



  * Emitted when camera permission is granted by the user



* `camera_permission_denied()`



  * Emitted when camera permission is denied by the user



* `frame_available(frame: FrameInfo)`



  * Emitted when a new camera frame is available






##  Methods



* `has_camera_permission() -> bool`



  * Returns whether camera permission has already been granted



* `request_camera_permission()`



  * Requests camera permission from the OS



* `get_all_cameras() -> Array[CameraInfo]`



  * Returns a list of available cameras



* `create_feed_request() -> FeedRequest`



  * Creates a `FeedRequest` pre-populated with the node's exported property values (`frame_width`, `frame_height`, `frames_to_skip`, `frame_rotation`, `is_grayscale`, `mirror_horizontal`, `mirror_vertical`, `scale_width`, `scale_height`, `auto_upright`)



* `start(request: FeedRequest)`



  * Starts the camera feed with the given configuration



* `stop()`



  * Stops the active camera feed






##  Classes



This section documents the GDScript interface classes implemented and exposed by the plugin.



###  CameraInfo



Encapsulates camera metadata provided by the mobile OS.



**Properties / Methods:**



* `get_camera_id() -> String`

* `is_front_facing() -> bool`

* `get_output_sizes() -> Array[FrameSize]`

* `get_sensor_orientation() -> int`

  * Returns the clockwise angle in degrees (`0`, `90`, `180`, or `270`) that the camera sensor image must be rotated to be upright when the device is held in its natural (portrait) orientation. This value is a fixed hardware property of the camera and does not change with device rotation. Defaults to `0` when the value is unavailable (e.g. on emulators). Useful when implementing custom frame processing that needs to account for sensor mounting angle independently of device orientation.



###  FeedRequest



Defines configuration parameters for starting a camera feed.



**Configurable options:**



* Camera ID

* Output width and height

* Frames to skip (performance tuning)

* Rotation (degrees: 0, 90, 180, 270 — applied first; ignored when `auto_upright` is enabled)

* Grayscale capture

* Horizontal mirror (`mirror_horizontal`) — flips the frame left-to-right after rotation

* Vertical mirror (`mirror_vertical`) — flips the frame top-to-bottom after rotation

* Scale width and height (`scale_width`, `scale_height`) — resizes the pixel buffer to the given dimensions as the final post-processing step (after rotation and mirroring); both must be non-zero for scaling to take effect; defaults to 0 (disabled)

* **Auto-upright** (`auto_upright`) — when enabled, the plugin detects the current device orientation on every frame and automatically computes and applies the rotation needed to keep the image upright; the manual `rotation` value is ignored while this flag is active; defaults to `false`



Both mirror flags default to `false` and can be combined independently with any rotation value. Mirroring is applied as a post-processing step after rotation on both Android and iOS, so the axis labels always refer to the final upright image.



Scaling is applied after mirroring and uses nearest-neighbour interpolation, making it suitable for real-time use cases such as downscaling before CV inference. Setting either `scale_width` or `scale_height` to 0 disables scaling entirely.



When `auto_upright` is active, `FrameInfo.get_rotation()` reports the rotation that was actually applied to that frame, which changes dynamically as the device is tilted. This value can be used for diagnostics or to inform downstream processing.



Supports fluent chaining via setter methods.



**Setter methods:**



* `set_camera_id(value: String) -> FeedRequest`

* `set_width(value: int) -> FeedRequest`

* `set_height(value: int) -> FeedRequest`

* `set_frames_to_skip(value: int) -> FeedRequest`

* `set_rotation(value: int) -> FeedRequest`

* `set_grayscale(value: bool) -> FeedRequest`

* `set_mirror_horizontal(value: bool) -> FeedRequest`

* `set_mirror_vertical(value: bool) -> FeedRequest`

* `set_scale_width(value: int) -> FeedRequest`

* `set_scale_height(value: int) -> FeedRequest`

* `set_auto_upright(value: bool) -> FeedRequest`



###  FrameInfo



Represents a single captured frame.



**Accessors:**



* `get_buffer() -> PackedByteArray`

* `get_width() -> int`

* `get_height() -> int`

* `get_rotation() -> int`

* `is_grayscale() -> bool`

* `get_image() -> Image`



###  FrameSize



Represents a supported camera output resolution.



**Accessors:**



* `get_width() -> int`

* `get_height() -> int`

* `get_raw_data() -> Dictionary`






##  Platform-Specific Notes



### Android



* Ensure Android export templates are installed

* Enable Gradle build in export settings

* Camera permission is required at runtime

* The **"Two-Strike" Rule**: Starting in Android 11, if a user taps "Deny" for a specific permission more than once during the app's lifetime on the device, the system will no longer show the dialog for future requests. Once this two-strike threshold is reached, any subsequent calls to request the permission will immediately be denied without showing any dialogs.



**Auto-upright on Android:**



When `auto_upright` is enabled the plugin reads the camera's `SENSOR_ORIENTATION` value (0, 90, 180, or 270°) from `CameraCharacteristics` once when the camera opens, and reads the live device rotation from `Display.getRotation()` on every processed frame. The required rotation is computed using the standard Camera2 formula:



| Camera type | Formula |

| :---------- | :------ |

| Back-facing | `(sensorOrientation − deviceDegrees + 360) % 360` |

| Front-facing | `(sensorOrientation + deviceDegrees + 360) % 360` |



Front cameras use addition rather than subtraction because their sensor image is horizontally mirrored, so the sensor and device rotations reinforce each other.



**Troubleshooting:**



* Logs (Linux/macOS): `adb logcat | grep godot`

* Logs (Windows): `adb.exe logcat | select-string "godot"`



Helpful resources:



* Godot Android export documentation

* Android Studio & ADB documentation



### iOS



* Follow Godot's iOS export instructions

* Camera permission must be declared in the generated Xcode project

* Use Xcode console logs for debugging



**Auto-upright on iOS:**



When `auto_upright` is enabled the plugin subscribes to `UIDevice.orientationDidChangeNotification` (started and stopped alongside the camera session) and caches the most recently observed `UIDeviceOrientation`. On every processed frame it maps that orientation to the rotation degrees needed to make the raw sensor buffer upright:



| `UIDeviceOrientation` | Back camera | Front camera |

| :-------------------- | :---------- | :----------- |

| `.portrait` | 90° | 90° |

| `.portraitUpsideDown` | 270° | 270° |

| `.landscapeLeft` *(top points left)* | 0° | 180° |

| `.landscapeRight` *(top points right)* | 180° | 0° |

| `.faceUp` / `.faceDown` / `.unknown` | 90° *(portrait fallback)* | 90° *(portrait fallback)* |



Front and back cameras produce mirrored values in the landscape cases because the front sensor image is horizontally flipped relative to the back sensor. Portrait orientations are the same for both camera types because the mirror axis does not interact with a 90°/270° rotation.










#  Links



* [AssetLib Entry Android](https://godotengine.org/asset-library/asset/4675)

* [AssetLib Entry iOS](https://godotengine.org/asset-library/asset/4676)










#  All Plugins



| ✦ | Plugin | Android | iOS | Latest Release | Downloads | Stars |

| :--- | :--- | :---: | :---: | :---: | :---: | :---: |

|  | [Admob](https://github.com/godot-sdk-integrations/godot-admob) | ✅ | ✅ |  |  |  |

|  | [Connection State](https://github.com/godot-mobile-plugins/godot-connection-state) | ✅ | ✅ |  |  |  |

|  | [Deeplink](https://github.com/godot-mobile-plugins/godot-deeplink) | ✅ | ✅ |  |  |  |

|  | [Firebase](https://github.com/godot-mobile-plugins/godot-firebase) | ✅ | ✅ |  |  |  |

|  | [In-App Review](https://github.com/godot-mobile-plugins/godot-inapp-review) | ✅ | ✅ |  |  |  |

|  | [Native Camera](https://github.com/godot-mobile-plugins/godot-native-camera) | ✅ | ✅ |  |  |  |

|  | [Notification Scheduler](https://github.com/godot-mobile-plugins/godot-notification-scheduler) | ✅ | ✅ |  |  |  |

|  | [OAuth 2.0](https://github.com/godot-mobile-plugins/godot-oauth2) | ✅ | ✅ |  |  |  |

|  | [QR](https://github.com/godot-mobile-plugins/godot-qr) | ✅ | ✅ |  |  |  |

|  | [Share](https://github.com/godot-mobile-plugins/godot-share) | ✅ | ✅ |  |  |  |

|  | [Vision](https://github.com/godot-mobile-plugins/godot-vision) | ✅ | ✅ |  |  |  |










#  Credits



Developed by [Cengiz](https://github.com/cengiz-pz)



Based on [Godot Mobile Plugin Template v7](https://github.com/godot-mobile-plugins/godot-plugin-template/tree/v7)



Original repository: [Godot Native Camera Plugin](https://github.com/godot-mobile-plugins/godot-native-camera)










#  Contributing



Contributions are welcome. Please see the [contributing guide](https://github.com/godot-mobile-plugins/godot-native-camera?tab=contributing-ov-file) in the repository for details.







# 💖 Support the Project



If this plugin has helped you, consider supporting its development! Every bit of support helps keep the plugin updated and bug-free.



| ✦ | Ways to Help | How to do it |

| :--- | :--- | :--- |

|✨⭐| **Spread the Word** | [Star this repo](https://github.com/godot-mobile-plugins/godot-native-camera/stargazers) to help others find it. |

|💡✨| **Give Feedback** | [Open an issue](https://github.com/godot-mobile-plugins/godot-native-camera/issues) or [suggest a feature](https://github.com/godot-mobile-plugins/godot-native-camera/issues/new). |

|🧩| **Contribute** | [Submit a PR](https://github.com/godot-mobile-plugins/godot-native-camera?tab=contributing-ov-file) to help improve the codebase. |

|❤️| **Buy a Coffee** | Support the maintainers on GitHub Sponsors or other platforms. |







## ⭐ Star History



[![Star History Chart](https://api.star-history.com/svg?repos=godot-mobile-plugins/godot-native-camera&type=date&theme=dark&legend=top-left)](https://www.star-history.com/?repos=godot-mobile-plugins%2Fgodot-native-camera&type=date&theme=dark&legend=top-left)