public final class

HVTCamera

extends Object
java.lang.Object
   ↳ com.hvt.horizonSDK.HVTCamera

Class Overview

You can use a HVTCamera object to establish a connection with the camera, attach a HVTView, capture videos and photos.

Leveling

When HVTCamera is running, it processes and corrects the camera video frames in real time by utilizing the internal leveler. This makes sure, that the final frame (video or photo) is leveled (stays parallel to the horizon). This is done by selecting a smaller rectangle inside the original video frame, which we'll refer to as "the crop region". The crop region can be displayed as a bright rectangle in HVTView, so that the user knows which part of the image will be used in the output. When outputting a photo or an image, HVTCamera receives a camera frame and transforms it (by scaling and rotating) so that the output contains only the crop frame.

You can read more about the leveling process in the leveler's setter methods: setLevelerCropMode(), setLevelerFlexSpeed() and setLevelerLockedOrientation().

Some properties are animated and can be changed even while recording, producing smooth transitions in the resulting video.

Asynchronous methods

Most of HVTCamera's methods are asynchronous. They make a request and HVTCamera processes it on the background. You should implement HVTCameraListener interface, to be notified about the methods' outcome. Each method, explains the listener methods it calls.

State requirement

HVTCamera is initially stopped. Starting it and stopping it is asynchronous as explained previously.

You can get the current state by calling, isRunning(), isRunningIdle(), isStopped(), isStartingRecording(), isStoppingRecording(), isRecording() .

Some methods require a specific state in order to work. Otherwise they have no effect. For example, calling startRecording() when HVTCamera is not running, will have no effect. Each method, explains the state required to work.

As a rule of thumb, when isRunningIdle() returns true, HVTCamera is running and is not working on a previous method call. In this case, you can call a new method.

Usage

Example usage:

Lifecycle

Usually an HVTCamera instance is tied to the lifecycle of an activity. So, the following methods are called for each Activity method:

However, an HVTCamera instance can work independently to an activity. For example, it could run inside a background service. In general, the methods can be called according to the app's use case.

Camera settings

In order to query the available cameras on the device, the supported video and photo sizes and other properties, you can use CameraHelper.

Then, call setCamera() to select a front or back facing camera, set a video and picture size. As explained in the method's description, it can be called while HVTCamera is stopped or running. However, you can't change the camera parameters while video recording or capturing a photo.

Output settings

By default, the size of a recorded movie is the same as the camera video size that was set when setCamera() was called. However, you can specify a different output movie size by calling setOutputMovieSize(Size). You can think of the the camera video size, as the size of the frame received by the device's camera and the output movie size as the size of the canvas on which the camera frame will be rendered on.

For example, the camera video size could be 1920x1080, while the movie size is 640x480. Internally, a 1920x1080 video frame will be processed to output a 640x480 frame. This can produce sharper results than setting the camera video size to 640x480.

Note that when startRecording() is called, you must provide a HVTCamcorderProfile having the same size as the output movie size, not the camera video size.

Performance and general considerations

While HVTCamera is running and recording, it stresses the device's CPU and GPU and also drains the battery. Using a high video resolution for a large amount of time, can cause CPU throttling and cause frame drops.

If the app is intended to be used with the screen closed, you can call detachPreviewView(HVTView) to stop updating the preview. This can save battery life. Also, If the activity that owns the attached HVTView view is destroyed but the HVTCamera instance is kept alive, the view need to be detached, or else it will leak.

The SDK does not take into account the available free space left. If HVTCamera is recording and the device rans out of space, the SDK will throw an exception.

HVTCamera sets the device's camera to video or picture mode depending on the current getCameraMode(). By default, it uses picture mode and automatically switches to video mode when recording. Some devices don't handle well this transition. If your app has a video-only or photo-only mode, it's best to call setCameraMode(HVTVars.CameraMode) with the appropriate mode, before calling startRunning(). This way, the device's camera will use a single mode. If the problem persists, you can enable setCompatibilityMode(boolean).

Summary

Public Constructors
HVTCamera(Context context)
Creates a new HVTCamera instance.
Public Methods
void attachPreviewView(HVTView view)
Attaches an HVTView in order to display a video preview.
void capturePhoto(File photoFile)
Requests to capture a photo.
void captureSnapshot(File photoFile)
Captures a snapshot while recording.
boolean compatibilityModeEnabled()
Returns if compatibility mode is enabled.
void destroy()
Release resources.
void detachPreviewView(HVTView view)
Detaches an HVTView.
int getCameraFacing()
Returns the current camera facing.
HVTVars.CameraMode getCameraMode()
Returns the current camera mode.
Size getCameraPictureSize()
Returns the current camera picture size.
Size getCameraVideoSize()
Returns the current camera video size.
String getFlashMode()
Gets the requested flash mode
HVTVars.HVTLevelerCropMode getLevelerCropMode()
Gets the crop mode used by the leveler.
HVTVars.HVTLevelerFlexSpeed getLevelerFlexSpeed()
Get the speed used by the leveler when crop mode is set to FLEX.
HVTVars.HVTLevelerLockedOrientation getLevelerLockedOrientation()
Get the orientation used by the leveler when crop mode is set to LOCKED.
HVTCameraListener getListener()
Returns the current listener.
Size getOutputMovieSize()
Returns the output move size of the final video file.
boolean isRecording()
Returns if HVTCamera is recording.
boolean isRunning()
Returns true if HVTCamera is running.
boolean isRunningIdle()
Returns true if HVTCamera is running and it not busy.
boolean isStartingRecording()
Returns if HVTCamera is starting the recording process.
boolean isStopped()
Returns true if HVTCamera is not running.
boolean isStoppingRecording()
Returns if HVTCamera is in the process of stopping recording.
void onFrameDropped(FrameDroppedEvent e)
void onSensorNotResponding(SensorNotRespondingEvent e)
void onSensorResponded(SensorRespondedEvent e)
void setCamera(int facing, Size videoSize, Size pictureSize)
Selects a front or back facing camera and sets a video and picture size.
void setCameraMode(HVTVars.CameraMode mode)
Sets the camera mode.
void setCompatibilityMode(boolean enabled)
Enables or disables compatibility mode.
void setFlashMode(String flashMode)
The requested flash mode.
void setLevelerCropMode(HVTVars.HVTLevelerCropMode cropMode)
Specifies which crop mode will be used by the leveler.
void setLevelerFlexSpeed(HVTVars.HVTLevelerFlexSpeed flexSpeed)
Specifies how fast the leveler zooms when leveler's crop mode is set to FLEX.
void setLevelerLockedOrientation(HVTVars.HVTLevelerLockedOrientation orientation)
Informs the leveler of the expected device orientation when crop mode is set to LOCKED.
void setListener(HVTCameraListener listener)
Set a listener, in order to get updates on HVTCamera's status.
void setOutputMovieSize(Size frameSize)
Specifies the output movie size of the final video file.
void setScreenRotation(int rotation)
Sets the rotation of the screen as defined in getRotation().
void setSensor(int sensorType, File calibrationFile)
Sets the device motion sensor and the corresponding calibration file that the level will use.
void setWatermarkEnabled(boolean enabled)
Specifies it a watermark will be drawn on top of the captured photos and videos.
void startRecording(File outputFile, HVTCamcorderProfile profile)
Requests to start the recording process.
void startRunning()
Requests to start the camera.
void stopRecording()
Requests to stop the recording process.
void stopRunning()
Requests to stop the camera.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public HVTCamera (Context context)

Creates a new HVTCamera instance.

Parameters
context an application context

Public Methods

public void attachPreviewView (HVTView view)

Attaches an HVTView in order to display a video preview.

Note: If the activity that owns the attached HVTView view is destroyed but the HVTCamera instance is kept alive, you should detach the HVTView, or else it will leak.

An HVTView instance can be attached and detached multiple times, regardless of HVTCamera's state. For example, HVTCamera could be running, stopping, recording etc.

Parameters
view an HVTView instance

public void capturePhoto (File photoFile)

Requests to capture a photo.

When the photo capture process completes, onPhotoCaptured(File, boolean) is called.

Note: You must call this method only if isRunningIdle() returns true.

Parameters
photoFile the file the photo will be saved

public void captureSnapshot (File photoFile)

Captures a snapshot while recording.

While recording, you can not call capturePhoto(File) to take a full resolution photo. However, you can call this method to take a video frame and save it as a picture. The dimensions will be the same as the movie (getOutputMovieSize()).

Note: You must call this only if the recording process is active. This happens between calls to onRecordingHasStarted() and onRecordingWillStop().

Parameters
photoFile the file the snpashot will be saved

public boolean compatibilityModeEnabled ()

Returns if compatibility mode is enabled.

Returns
  • true if compatibility mode is enabled

public void destroy ()

Release resources. After this call, this instance may no longer be used.

If isStopped() is true, the call blocks until the instance is destroyed.

If it is called while the instance is running, the call will return instantly. Internally, stopRunning() will be called first and destroy() afterwards.

If it is called while recording, the call will return instantly. Internally stopRecording(), will be called, then stopRunning() and finally destroy().

public void detachPreviewView (HVTView view)

Detaches an HVTView. Video preview will stop on the view.

This can be useful, if the HVTCamera instance is recording while the app is the background. There is no need to update the view, since the screen is closed.

Parameters
view the HVTView which will be detached.

public int getCameraFacing ()

Returns the current camera facing.

public HVTVars.CameraMode getCameraMode ()

Returns the current camera mode.

Returns
  • the current camera mode

public Size getCameraPictureSize ()

Returns the current camera picture size.

Returns
  • the camera size used for photo capturing

public Size getCameraVideoSize ()

Returns the current camera video size.

Returns
  • the camera size used for video recording

public String getFlashMode ()

Gets the requested flash mode

Returns
  • the requested flash mode

public HVTVars.HVTLevelerCropMode getLevelerCropMode ()

Gets the crop mode used by the leveler.

Returns
  • the crop mode used by the leveler.

public HVTVars.HVTLevelerFlexSpeed getLevelerFlexSpeed ()

Get the speed used by the leveler when crop mode is set to FLEX.

Returns

public HVTVars.HVTLevelerLockedOrientation getLevelerLockedOrientation ()

Get the orientation used by the leveler when crop mode is set to LOCKED.

Returns

public HVTCameraListener getListener ()

Returns the current listener.

Returns
  • the current listener of HVTCamera or `null`

public Size getOutputMovieSize ()

Returns the output move size of the final video file.

Note: the default value matches the camera video size, unless setOutputMovieSize(Size) is called.

Returns
  • the output movie size of the final video file

public boolean isRecording ()

Returns if HVTCamera is recording.

It returns true, when startRecording() is called and turns to false when onRecordingFinished(File, boolean) is called. This means that it stays true for some time even after a call to stopRecording().

Returns
  • true if recording

public boolean isRunning ()

Returns true if HVTCamera is running.

Note: when it returns true, isRunningIdle() can be true or false.

Returns
  • true if the instance is running.

public boolean isRunningIdle ()

Returns true if HVTCamera is running and it not busy.

When true, HVTCamera is running and is free to process another method call. It turns to false, when HVTCamera is running but is busy processing a previous call. For example, if it returns true, you can call capturePhoto(File). After you make this call and until HVTCamera completes the capture process, it will return false.

Note: If it returns true, isRunning() should also return true. The reverse does not stand.

Returns
  • true if the instance is just running and is not busy.

public boolean isStartingRecording ()

Returns if HVTCamera is starting the recording process.

Gets true when startRecording(File, HVTCamcorderProfile) is called and turns false when onRecordingHasStarted() is called.

Returns
  • true if the recording process has just started

public boolean isStopped ()

Returns true if HVTCamera is not running. The camera device is not accessed at this time.

Note: when stopRunning() is called, this method will initially return false. Only when HVTCamera has actually stopped running, will it return true.

Returns
  • true if the instance is not running.

public boolean isStoppingRecording ()

Returns if HVTCamera is in the process of stopping recording.

It returns true when stopRecording() is called and turns to false when onRecordingFinished(File, boolean) is called.

Returns
  • true if recording process is being stopped.

public void onFrameDropped (FrameDroppedEvent e)

public void onSensorNotResponding (SensorNotRespondingEvent e)

public void onSensorResponded (SensorRespondedEvent e)

public void setCamera (int facing, Size videoSize, Size pictureSize)

Selects a front or back facing camera and sets a video and picture size.

You must first query the device's available cameras the supported video and picture sizes by calling the respective methods of CameraHelper. Setting unsupported values, will fail to start HVTCamera.

Even though you can set a different videoSize and pictureSize, it is important to have the same aspect ratio. If you want to specify one of them and get a compatible size for the other, you can use getVideoSizesForPhotoSize(int, Size) and getPhotoSizesForVideoSize(int, Size).

Note: The facing of the camera is required, not the camera id.

Note: You must call this method only if isStopped() returns true or isRunningIdle() returns true. In the first case, the method just sets the requested settings and applies them when startRunning() is called. In the second case, HVTCamera will stop running, the requested settings will be applied and it will start running again. The listener methods described in startRunning() and stopRunning() will be called.

Parameters
facing CAMERA_FACING_BACK or CAMERA_FACING_FRONT
videoSize the size used for video recording
pictureSize the size used for photo capturing

public void setCameraMode (HVTVars.CameraMode mode)

Sets the camera mode.

The camera mode optimizes some camera settings for video or photo use.

In video mode, the default focus mode is set to FOCUS_MODE_CONTINUOUS_VIDEO and setRecordingHint(boolean) is enabled. In picture mode, the default focus mode is set to FOCUS_MODE_CONTINUOUS_PICTURE and setRecordingHint(boolean) is disabled. In, auto mode, the settings of picture mode are used by default. When recording starts, the settings of video mode are set temporarily.

Parameters
mode the requested camera mode

public void setCompatibilityMode (boolean enabled)

Enables or disables compatibility mode.

If enabled, setRecordingHint(boolean) will always be set to false regardless of the current camera mode.

Parameters
enabled set to true to enable compatibility mode

public void setFlashMode (String flashMode)

The requested flash mode.

Note: If the camera does not support the requested flash mode, nothing will happen. The requested flash mode remains the same through calls to setCamera().

Parameters
flashMode one of the supported flash mode defined in getFlashMode()

public void setLevelerCropMode (HVTVars.HVTLevelerCropMode cropMode)

Specifies which crop mode will be used by the leveler.

HVTCamera crops each camera frame so that the resulting frame is leveled. This involves rotating and scaling the crop region, prior to cropping the frame, according to the device's physical orientation at that time. The crop mode is the way the leveler adjusts the rotation and scale of the crop region. You can read what each mode does in HVTVars.HVTLevelerCropMode.

Note that scaling up/down the crop region equals to zooming out/in the original camera frame.

The property is animated.

The default value is FLEX.

Parameters
cropMode the crop mode to set in the leveler

public void setLevelerFlexSpeed (HVTVars.HVTLevelerFlexSpeed flexSpeed)

Specifies how fast the leveler zooms when leveler's crop mode is set to FLEX.

The default value is SMOOTH

Parameters
flexSpeed the speed to be used by the leveler when crop mode is set to FLEX

public void setLevelerLockedOrientation (HVTVars.HVTLevelerLockedOrientation orientation)

Informs the leveler of the expected device orientation when crop mode is set to LOCKED.

Since leveling is disabled when crop mode is LOCKED, this property should match the device's physical orientation. The leveler uses this information to rotate the incoming video frame, if needed, by multiples of 90 degrees so that it does not appear upside down or having wrong orientation. You can read more about the process, in LOCKED reference.

For example, if the user is intended to hold the device vertically, use VERTICAL.

The property is animated.

The default value is AUTO.

Parameters
orientation the orientation used by the leveler when crop mode is set to LOCKED.

public void setListener (HVTCameraListener listener)

Set a listener, in order to get updates on HVTCamera's status.

Some of HVTCamera's methods return their result by calling the corresponding methods of HVTCameraListener.

You can set it to null, to stop receiving updates.

Note: You should not call a HVTCamera method that makes a request (eg startRunning(), stopRunning(), setCamera(), startRecording() from within a HVTCameraListener) method. Post a Runnable if you need to.

Parameters
listener the listener to set to HVTCamera

public void setOutputMovieSize (Size frameSize)

Specifies the output movie size of the final video file.

The output movie size can differ from the camera video size. For example, you can have a 1920x1080 camera video size and a 640x640 final video file. While the camera video size specifies the size of the incoming video frames by the camera, the output movie size specifies the size of the frame they will be rendered on.

The aspect ratio of the crop frame that is displayed on the HVTView is the aspect ratio of the output movie size.

If a photo is taken, it will have the same aspect ratio as the movie, but its resolution will be related to the picture size.

Even though the video size set to setCamera() must be supported by the camera, the output movie size doesn't have this restriction. However, the video encoder of the device may not support it. Unfortunately, there is no way to check that beforehand. Setting a not supported movie size, will throw an exception when recording starts. As rule of thumb, width and height must be multiples of 4 and they shouldn't be higher that the maximum camera video size of the device.

Note: the default value matches the camera video size, unless this method is called. Every time setCamera(int, Size, Size) is called, output movie size is reset.

Note: You can't call this method, while recording or photo capturing.

Parameters
frameSize the frame size of the recorded movie

public void setScreenRotation (int rotation)

Sets the rotation of the screen as defined in getRotation().

HVTCamera will adjust the orientation of the attached HVTView and the angle returned by onAngleUpdated(float, float) to match the supplied screen rotation.

If your activity changes orientation, you should call this method whenever it changes:

int activityRotation = getWindowManager().getDefaultDisplay().getRotation();
mHVTCamera.setScreenRotation(activityRotation);   

Parameters
rotation the rotation of the screen in degrees as defined in getRotation().

public void setSensor (int sensorType, File calibrationFile)

Sets the device motion sensor and the corresponding calibration file that the level will use.

The sensor used by leveler can either be the accelerometer or gravity sensor. The latter has the most accurate performance, but some devices don't support it.

By default, HVTCamera will auto select the best sensor. If gravity sensor is not available it will use the accelerometer.

Note: the calibration file is created when the user run the calibration activity. It is currently not available via the SDK.

Parameters
sensorType can be any of TYPE_ACCELEROMETER, TYPE_GRAVITY or -1 to auto select
calibrationFile a calibration file created by the calibration activity that corrects the sensor's readings

public void setWatermarkEnabled (boolean enabled)

Specifies it a watermark will be drawn on top of the captured photos and videos.

The watermark is placed in the bottom right corner of the output. You can alter the drawable used to draw the watermark, its opacity and its scale by overriding the following xml values:

<drawable name="hvt_watermark">@drawable/horizon_watermark</drawable>
<item name="hvt_watermark_scale" format="float" type="dimen">1.0</item>
<item name="hvt_watermark_opacity" format="float" type="dimen">0.75</item>  

The default value is false.

Parameters
enabled if true a watermark will be drawn

public void startRecording (File outputFile, HVTCamcorderProfile profile)

Requests to start the recording process.

You can specify the recording options via the provided profile. Note that the width and height of the profile should match the ones set it getOutputMovieSize(). So, if you want to change the output movie size, call setOutputMovieSize(Size) first and set the same width and height in the provided profile.

The recording process has 3 states: starting recording, actual recording, stopping recording. Under all states, isRecording() returns true. After calling this method the following events occur:

Note: You must call this method only if isRunningIdle() returns true.

Parameters
outputFile the file where the movie will be saved.
profile the audio and video settings, that will be used for the resulting movie file. The width and height provided must match the values returned by getOutputMovieSize().

public void startRunning ()

Requests to start the camera.

When HVTCamera has actually started running, an attached HVTView will show the camera preview. Other methods can be called so that, video recording and photo capture can take place. When the method is called, the following take place:

If stopRunning() has been called and HVTCamera had not stopped running yet, you can still call this method. However, HVTCamera will first fully stop and then it will start again. All listener methods will be called.

See Also

public void stopRecording ()

Requests to stop the recording process.

When this method is called the following events take place:

Note: You must call this method only if isRecording() returns true and after onRecordingHasStarted() has been called.

public void stopRunning ()

Requests to stop the camera.

When the method is called, the following take place:

If it is called while recording, it will internally call stopRecording() and then stopRunning().