diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..ee9a439 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,3 @@ +github: defold +patreon: Defold +custom: ['https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NBNBHTUW4GS4C'] diff --git a/.github/workflows/trigger-site-rebuild.yml b/.github/workflows/trigger-site-rebuild.yml new file mode 100644 index 0000000..64343db --- /dev/null +++ b/.github/workflows/trigger-site-rebuild.yml @@ -0,0 +1,19 @@ +name: Trigger site rebuild + +on: [push] + +jobs: + site-rebuild: + runs-on: ubuntu-latest + + steps: [ + { + name: 'Repository dispatch', + uses: defold/repository-dispatch@1.2.1, + with: { + repo: 'defold/defold.github.io', + token: '${{ secrets.GITHUB_TOKEN }}', + user: 'services@defold.se', + action: 'extension-camera' + } + }] diff --git a/README.md b/README.md index c06b590..9d84338 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,5 @@ -# extension-camera +# Camera extension for Defold -Native extension to use device camera to capture frames. +Defold [native extension](https://www.defold.com/manuals/extensions/) which provides access to the camera on macOS, iOS and Android. - -# Installation - -To use the camera extension in a Defold project this project has to be added as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open the **game.project** file and in the [Dependencies field in the Project section](https://defold.com/manuals/project-settings/#dependencies) add: - -https://github.com/defold/extension-camera/archive/master.zip - -Or point to the ZIP file of [a specific release](https://github.com/defold/extension-camera/releases). - - -# Supported platforms - -The currently supported platforms are macOS, iOS and Android - - -# FAQ - -## How do I reset macOS camera permission? - -To test macOS camera permission popup multiple times you can reset the permission from the terminal: - -```bash -tccutil reset Camera -``` - - -# Lua API - -## Type constants - -Describes what camera should be used. - -```lua -camera.CAMERA_TYPE_FRONT -- Selfie -camera.CAMERA_TYPE_BACK -``` - - -## Quality constants - -```lua -camera.CAPTURE_QUALITY_HIGH -camera.CAPTURE_QUALITY_MEDIUM -camera.CAPTURE_QUALITY_LOW -``` - - -## Status constants - -```lua -camera.CAMERA_STARTED -camera.CAMERA_STOPPED -camera.CAMERA_NOT_PERMITTED -camera.CAMERA_ERROR -``` - - -## camera.start_capture(type, quality, callback) - -Start camera capture using the specified camera (front/back) and capture quality. This may trigger a camera usage permission popup. When the popup has been dismissed the callback will be invoked with camera start status. - -```lua -camera.start_capture(camera.CAMERA_TYPE_BACK, camera.CAPTURE_QUALITY_HIGH, function(self, message) - if message == camera.CAMERA_STARTED then - -- do stuff - end -end) -``` - - -## camera.stop_capture() - -Stops a previously started capture session. - -```lua -camera.stop_capture() -``` - - -## camera.get_info() - -Gets the info from the current capture session. - -```lua -local info = camera.get_info() -print("width", info.width) -print("height", info.height) -``` - - -## camera.get_frame() - -Retrieves the camera pixel buffer. This buffer has one stream named "rgb", and is of type `buffer.VALUE_TYPE_UINT8` and has the value count of 1. - -```lua -self.cameraframe = camera.get_frame() -``` +[Manual, API and setup instructions](https://www.defold.com/extension-camera/) is available on the official Defold site. diff --git a/camera/api/extension-camera.script_api b/camera/api/extension-camera.script_api new file mode 100644 index 0000000..6c1e29a --- /dev/null +++ b/camera/api/extension-camera.script_api @@ -0,0 +1,121 @@ +- name: camera + type: table + desc: Provides functionality to capture images using the camera. Supported on macOS, iOS and Android. + [icon:ios] [icon:android] + members: + +#***************************************************************************************************** + + - name: start_capture + type: function + desc: Start camera capture using the specified camera (front/back) and capture quality. This may trigger a camera usage permission popup. When the popup has been dismissed the callback will be invoked with camera start status. + + members: + - name: type + type: string + desc: Which camera to use, font or back. + - name: quality + type: string + desc: Quality of the captured image. + - name: callback + type: function + desc: |- + The function to call camera state has changed. + + examples: + - desc: |- + ```lua + camera.start_capture(camera.CAMERA_TYPE_BACK, camera.CAPTURE_QUALITY_HIGH, function(self, message) + if message == camera.CAMERA_STARTED then + -- do stuff + end + end) + ``` + +#***************************************************************************************************** + + - name: stop_capture + type: function + desc: Stops a previously started capture session. + + examples: + - desc: |- + ```lua + camera.stop_capture() + ``` + +#***************************************************************************************************** + + - name: get_info + type: function + desc: Gets the info from the current capture session. + return: + - name: info + type: table + desc: Information about the camera. + + examples: + - desc: |- + ```lua + local info = camera.get_info() + print("width", info.width) + print("height", info.height) + ``` + +#***************************************************************************************************** + + - name: get_frame + type: function + desc: Get captured frame. + return: + - name: frame + type: buffer + desc: Retrieves the camera pixel buffer. This buffer has one stream named "rgb", and is of type `buffer.VALUE_TYPE_UINT8` and has the value count of 1. + + examples: + - desc: |- + ```lua + self.cameraframe = camera.get_frame() + ``` + +#***************************************************************************************************** + + - name: CAMERA_TYPE_FRONT + type: string + desc: Constant for the front camera. + + - name: CAMERA_TYPE_BACK + type: string + desc: Constant for the back camera. + +#***************************************************************************************************** + + - name: CAPTURE_QUALITY_HIGH + type: string + desc: High quality capture session. + + - name: CAPTURE_QUALITY_MEDIUM + type: string + desc: Medium quality capture session. + + - name: CAPTURE_QUALITY_LOW + type: string + desc: Low quality capture session. + +#***************************************************************************************************** + + - name: CAMERA_STARTED + type: string + desc: The capture session has started. + + - name: CAMERA_STOPPED + type: string + desc: The capture session has stopped. + + - name: CAMERA_NOT_PERMITTED + type: string + desc: The user did not give permission to start the capture session. + + - name: CAMERA_ERROR + type: string + desc: Something went wrong when starting the capture session. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..76635e9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,67 @@ +--- +title: Defold camera extension API documentation +brief: This manual covers how to use the camera on macOS, iOS and Android in Defold. +--- + +# Defold camera extension API documentation + +This extension provides a unified, simple to use interface to capture images using the camera on macOS, iOS and Android. + + +## Installation +To use this library in your Defold project, add the following URL to your `game.project` dependencies: + +https://github.com/defold/extension-camera/archive/master.zip + +We recommend using a link to a zip file of a [specific release](https://github.com/defold/extension-camera/releases). + + +## Configuration +The extension can be configured by adding the following fields to game.project: + +``` +[adinfo] +tracking_usage_description = We would like to show you relevant ads. +register_for_attribution = 1 +``` + +### tracking_usage_description + +Before requesting advertising info and status on iOS 14 the application must request user authorization to access app-related data for tracking the user or the device. This is done automatically when `adinfo.get()` is called. The string set in `adinfo.tracking_usage_description` will be shown to the user. + +Apple documentation: https://developer.apple.com/documentation/apptrackingtransparency?language=objc + +### register_for_attribution + +The extension can automatically register the application for ad network attribution using `SkAdNetwork` and the `registerAppForAdNetworkAttribution()` function. Enable this functionality by setting `adinfo.register_for_attribution` to 1 in game.project. + +Apple documentation: https://developer.apple.com/documentation/storekit/skadnetwork + + +## Example + +```lua +function init(self) + adinfo.get(function(self, info) + print(info.ad_ident, info.ad_tracking_enabled) + end) +end +``` + +## FAQ + +### How do I reset macOS camera permission? + +To test macOS camera permission popup multiple times you can reset the permission from the terminal: + +```bash +tccutil reset Camera +``` + + +## Source code + +The source code is available on [GitHub](https://github.com/defold/extension-adinfo) + + +## API reference