iOS Camera 0.9.0

A GameMaker: Studio extension developed by Beneton Software

Table of Contents

Requirements

This extension was fully tested on GameMaker: Studio v1.4.1772, compiling for both iOS and iOS (YYC). It was also successfully tested with GameMaker Studio 2 for Windows (v2.0.7.171), although it is not officially supported at the moment.

Getting Started

This extension package contains an example, in the form of GameMaker: Studio resources (sprites, objects, rooms, etc.) that can be imported in your project. This example is completely optional; it is meant to showcase what can be achieved with the extension, as well as help get familiarized with its functionality and quickly dive into the code. It is not meant to be used “as is”, and it doesn’t replace this documentation. If you wish to check out the example, we recommend adding the extension to an empty project, importing all the resources, moving the room that fits your device (phone or tablet) to the first position, and running it on your iOS or Android device (note: for Android, you have to create a full APK).

The iOS Camera extension allows you to access the iPhone or iPad camera(s) in your GameMaker: Studio game or application. It contains two sets of functions, depending on the level of control you need. The first one is the easiest to implement but it’s also the least customizable. It consists essentially of one function:

camera_launch_full_screen(position);

This function lets the user take a picture (not a video) using one of the device’s cameras. It uses iOS’s default “camera view” which will slide over your game’s view and stay there until the user takes a picture (or click on “Cancel”). The position argument determines which camera to use by default in the camera view (CAMERA_POSITION_BACK or CAMERA_POSITION_FRONT). The function itself doesn’t return anything because the process of taking a picture is asynchronous, but you can catch the picture that was taken by listening to the took_picture asynchronous event (see the “Events” section further in this document).

There is another simple function, and this one is useful even if you use the most advanced set of functions as it doesn’t have an advanced equivalent:

camera_launch_library();

As its name suggests, this function displays the photo library so the user can pick an existing photo from their device. Just like camera_launch_full_screen(), a view will slide over the game’s view and stay there until the user selects a picture or clicks on “Cancel”. In this case, the event to watch for is called picked. Also, both functions trigger a dismissed event when the user cancels them.

Whenever took_picture or picked is triggered, the async_load DS map contains a filename key that represents the name of the image file saved by the extension in the save area of your game. Which means that you can do what you want with it, like saving it to the device with camera_save_picture_to_library(), or adding it as a sprite like this:

var picture = sprite_add(async_load[? "filename"], 0, false, false, 0, 0);

An important note here: you probably don’t want to add pictures coming from the camera as is, due to their gigantic size (not to mention the JPEG format that is not ideal for GameMaker: Studio). That is why the extension has the function camera_process_picture(filename, format, maxWidth, maxHeight), where format is either CAMERA_FORMAT_JPEG or CAMERA_FORMAT_PNG. That function returns the filename of the modified file (the original one is preserved). So, you could do it like this:

var filename = async_load[? "filename"];
var processed_filename = camera_process_picture(filename, CAMERA_FORMAT_PNG, 300, 200);
var picture = sprite_add(processed_filename, 0, false, false, 0, 0);

You can also use camera_set_picture_format(format) and camera_set_picture_max_dimensions(width, height) for the same purpose, the difference being that these functions affect all the future pictures taken by the camera. You can set them globally at the beginning of your game, but you will lose the ability to retrieve the original images.

Let’s now move to the second, more advanced set of functions to access the camera. That kind of implementation usually starts with a call to the following function:

camera_enable(position, quality);

You can already see that it takes one more parameter, quality, which should be set to one of the CAMERA_QUALITY_* constants (see the “Constants” section further in this document). Once the camera is enabled (and you should make sure that it is by watching for the enabled event, or by polling with the function camera_is_enabled()), you can do anything from taking pictures to recording video, and you have full control over the UI (other than drawing over the preview layer). When you want to stop using the camera, simply call camera_disable(). Please note that the capture session can be interrupted by the OS in some situations, which will trigger the disabled event.

One important thing to know is that when your app calls camera_launch_full_screen() or camera_enable() for the first time, iOS will display a prompt asking the user permission to access the camera (and the microphone as well in the case of camera_enable(), unless you call camera_microphone_enable(false) beforehand). If the user denies the access request, the camera will remain disabled and the denied_access event will be triggered. Same thing for the functions that require access to the library (camera_launch_library(), camera_save_picture_to_library(), and camera_save_video_to_library()).

If you are writing a custom UI to control the camera, you probably want to display a preview of what the user is recording or taking a picture of somewhere on the screen. You can do that with:

camera_show_preview(x, y, width, height);

Please note that the coordinates and dimensions that you need to pass to that function are not relative to GameMaker: Studio’s room, nor are they relative to the view, GUI layer, surface, or anything like that. They are relative to the application’s root view, which is the size of your device’s screen, in points, not in pixels. On Retina displays (iPhone 4 and later), one point is 2 pixels wide by 2 pixels high. That means that the root view’s size is half the actual screen resolution in each dimension. Simply put, if your device is an iPhone 6 (actual resolution of 750 x 1334), and you want the camera preview to fill the whole screen, you would need: camera_show_preview(0, 0, 375, 667). Use the same function whenever you want to change the position or size of the preview. You can hide the preview at any moment with camera_hide_preview(). You can also change its scaling mode (fit, fill, or stretch) with camera_preview_set_scaling_mode() and its alpha transparency with camera_preview_set_alpha(). However, you cannot draw anything over the preview layer, as it is itself over your game’s layer.

Below is the complete list of functions. Notice that many of them require the camera to be enabled to work. It is strongly recommended to go over the example project to better understand how they all fit together. If you are experiencing any issue, please make sure to check out the “Troubleshooting” section at the bottom of this document. If you don’t find an answer to your question, don’t hesitate to contact us through the YoYo Games Marketplace (link at the top). Thank you!

Functions

camera_enable(position, quality)

Enables the camera.

Real position The camera to use; one of CAMERA_POSITION_BACK or CAMERA_POSITION_FRONT.

Real quality The image quality; one of the CAMERA_QUALITY_* constants.

Callback events: enabled, denied_access

camera_disable()

Disables the camera.

Callback event: disabled

camera_is_enabled()

Returns whether the camera is enabled.

Returns: Boolean

camera_exists(position)

Returns whether the given camera exists on the device.

Real position The camera to check for; one of CAMERA_POSITION_BACK or CAMERA_POSITION_FRONT.

Returns: Boolean

camera_get_position()

Returns the current camera (one of CAMERA_POSITION_BACK or CAMERA_POSITION_FRONT), or -1 if the camera is disabled.

Returns: Real

camera_get_quality()

Returns the current image quality (one of the CAMERA_QUALITY_* constants), or -1 if the camera is disabled.

Returns: Real

camera_take_picture()

Takes a picture with the current camera.

Callback event: took_picture

camera_is_taking_picture()

Returns whether the camera is currently in the process of taking a picture.

Returns: Boolean

camera_can_record()

Returns whether the current camera is capable of recording video (a camera with quality CAMERA_QUALITY_PHOTO is not).

Returns: Boolean

camera_start_recording()

Makes the current camera start recording video (if it’s capable).

camera_stop_recording()

Makes the current camera stop recording video (if it is recording).

Callback event: finished_recording

camera_is_recording()

Returns whether the camera is currently recording video.

Returns: Boolean

camera_show_preview(x, y, width, height)

Shows the camera preview at position (x, y) with dimensions width and height. If the aspect ratio of the camera’s captured images is different from the ratio of these dimensions, the images will be resized to fit, fill, or stretch to the preview area, depending on the current scaling mode (see camera_preview_set_scaling_mode()). The coordinates and dimensions are in points (on a Retina Display, 1 point = 2 x 2 pixels) and relative to the device’s screen.

Real x

Real y

Real width

Real height

camera_hide_preview()

Hides the camera preview.

camera_preview_is_visible()

Returns whether the camera preview is currently visible.

Returns: Boolean

camera_preview_set_scaling_mode(scaling_mode)

Sets the scaling mode of the camera preview. The default value is CAMERA_SCALING_MODE_FIT.

Real scaling_mode The new scaling mode; one of the CAMERA_SCALING_MODE_* constants.

camera_preview_set_alpha(alpha)

Sets the alpha transparency value of the camera preview. 1 is fully opaque, 0 is fully transparent, and anything in between is translucent. The default is 1.

Real alpha The new alpha transparency value; between 0 and 1, inclusively.

camera_get_width()

Returns the width of images captured by the current camera.

Returns: Real

camera_get_height()

Returns the height of images captured by the current camera.

Returns: Real

camera_set_flash(flash)

Sets the flash setting for the current camera. The default value is CAMERA_FLASH_OFF.

Real flash The new flash setting; one of the CAMERA_FLASH_* constants.

camera_get_flash()

Gets the value of the current camera’s flash option (one of the CAMERA_FLASH_* constants).

Returns: Real

camera_flash_is_available()

Returns whether the current camera has a flash and it is available to use.

Returns: Boolean

camera_launch_full_screen(position)

Launches the full screen camera view to take pictures. This camera is not affected by any of the previous functions, but it is affected by camera_set_picture_format() and camera_set_picture_max_dimensions().

Real position The camera to use; one of CAMERA_POSITION_BACK or CAMERA_POSITION_FRONT.

Callback events: took_picture, dismissed, denied_access

camera_launch_library()

Launches the photo library to select a picture from.

Callback events: picked, dismissed

camera_save_picture_to_library(filename)

Saves an image to the device’s library.

String filename The image to save.

Callback events: saved, failed_to_save, access_denied

camera_save_video_to_library(filename)

Saves a video to the device’s library.

String filename The video to save.

Callback events: saved, failed_to_save, access_denied

camera_process_picture(filename, format, max_width, max_height)

Converts an image to a specific format, and makes sure it does not exceed the given dimensions (scale down to fit). Returns the filename of the processed image (leaving the original intact).

String filename The image to convert.

Real format The format to convert to; one of the CAMERA_FORMAT_* constants.

Real max_width The maximum width of the converted image (-1 for no maximum).

Real max_height The maximum height of the converted image (-1 for no maximum).

Returns: String The filename of the converted image.

camera_set_picture_format(format)

Globally sets the format to use when saving pictures taken with the camera. The default is CAMERA_FORMAT_JPEG.

Real format The new image format; one of the CAMERA_FORMAT_* constants.

camera_set_picture_max_dimensions(width, height)

Globally sets the maximum dimensions to use when saving pictures taken with the camera. There are no maximum dimensions by default.

Real width The maximum width (-1 for no maximum).

Real height The maximum height (-1 for no maximum).

camera_microphone_enable(enable)

Globally sets whether the application should have access to the device’s microphone. The default value is true, meaning the first time your application enables the camera on a given device, iOS will request the user’s permission to use the microphone. To avoid that, execute camera_microphone_enable(false) before the call to camera_enable(). Please note that recorded video will have no sound if you do that.

Boolean enable Whether to enable the microphone.

camera_idle_timer_enable(enable)

Enables or disables the idle timer for the application. iOS applications created with GameMaker: Studio have the idle timer enabled by default, meaning the display will go to sleep if enough time passes without user interaction. That can be a problem with the camera because the display can go to sleep when you are recording video, stopping the recording automatically. You can prevent it from happening by calling camera_idle_timer_enable(false) beforehand.

Boolean enable Whether to enable the idle timer.

Events

This extension uses GameMaker: Studio’s way of providing callbacks via the Social asynchronous event. Whenever a Camera “event” happens, the Social event is triggered with an async_load DS map whose type key is camera. This helps you identify which callbacks come from this extension and which don’t. There is also a secondary key called event, a string identifying which event was triggered, among the following:

enabled
The camera finished starting up and is now ready to use.

disabled
The camera was disabled (programmatically or by the OS for some reason) and cannot be used until it is enabled again.

denied_access
The user explicitly denied to give the application access to a particular service. The service key holds a string identifying which service it is: camera, microphone, or library.

took_picture
The camera finished taking a picture and writing it to a file. The filename key holds the filename of the image, located in the save area of the application.

failed_to_take_picture
The camera failed to take a picture or writing it to a file. The reason can vary: the camera was disabled just after a call to camera_take_picture() and the picture was not taken, there is not enough storage available, there is a hardware problem, etc.

finished_recording
The camera finished recording a video and writing it to a file. The filename key holds the filename of the video, located in the save area of the application.

failed_to_finish_recording
The camera failed to record a video or writing it to a file. The reason can vary: there is not enough storage available, there is a hardware problem, etc.

saved
The extension finished saving a file to the library. The filename key tells you which file it is.

failed_to_save
The extension was not able to save a file to the library for some reason. The filename key tells you which file it is.

picked
The user picked a photo in the library and the extension finished writing it to a file. The filename key holds the filename of the image, located in the save area of the application.

dismissed
The user dismissed the full screen camera view or the image picker (library) by clicking on “Cancel”.

Constants

Camera Positions

Camera Quality

Preview Scaling Modes

Flash Modes

Image Formats

Troubleshooting

The game’s sounds and/or music start playing on the speakers when the camera is enabled, even when the device is set to “mute”.

Unfortunately, that is a side effect of changing the application’s audio session to “record and playback” mode, which is needed to record audio during video capture. There are two solutions: you can manually stop/pause any music when the camera is enabled (and start it again when it’s disabled), or you can turn off audio recording by calling camera_microphone_enable(false) before enabling the camera.

Changelog

0.9.0 (2016-10-31)

0.8.5 (2015-11-11)

0.8.0 (2015-10-31)