java.lang.Object | |
↳ | com.hvt.horizonSDK.HVTCamera |
You can use a HVTCamera object to establish a connection with the camera, attach a HVTView
,
capture videos and photos.
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.
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.
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.
Example usage:
setScreenRotation(int)
to set the activity's rotation.set
a HVTCameraListener
object.HVTView
by calling
attachPreviewView(HVTView)
setCamera(int, Size, Size)
to set the desired camera settings.startRunning()
to open the camera. Wait, until
onStartedRunning(Camera.Parameters, int)
is called.startRecording(File, HVTCamcorderProfile)
and wait until
onRecordingHasStarted()
is called.stopRecording()
.stopRunning()
to stop the camera. If you want to open the camera again later,
you can startRunning()
in the future.destroy()
if you don't want to use the instance any more. onCreate()
: HVTCamera(Context)
onResume()
startRunning()
onPause()
stopRunning()
onDestroy()
destroy()
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.
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.
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.
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)
.
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() | ||||||||||
HVTVars.HVTLevelerLockedOrientation | getLevelerLockedOrientation() | ||||||||||
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 |
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) | ||||||||||
void | setLevelerLockedOrientation(HVTVars.HVTLevelerLockedOrientation orientation) | ||||||||||
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
|
Creates a new HVTCamera instance.
context | an application context |
---|
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.
view | an HVTView instance |
---|
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
.
photoFile | the file the photo will be saved |
---|
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()
.
photoFile | the file the snpashot will be saved |
---|
Returns if compatibility mode is enabled.
true
if compatibility mode is enabledRelease 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()
.
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.
view | the HVTView which will be detached. |
---|
Returns the current camera facing.
Returns the current camera mode.
Returns the current camera picture size.
Returns the current camera video size.
Gets the crop mode used by the leveler.
Returns the current listener.
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 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()
.
true
if recording
Returns true
if HVTCamera is running.
Note: when it returns true
, isRunningIdle()
can be true
or false
.
true
if the instance is running.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.
true
if the instance is just running and is not busy.Returns if HVTCamera is starting the recording process.
Gets true
when startRecording(File, HVTCamcorderProfile)
is called and turns
false
when onRecordingHasStarted()
is called.
true
if the recording process has just started
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
.
true
if the instance is not running.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.
true
if recording process is being stopped.
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.
facing | CAMERA_FACING_BACK
or CAMERA_FACING_FRONT |
---|---|
videoSize | the size used for video recording |
pictureSize | the size used for photo capturing |
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.
mode | the requested camera mode |
---|
Enables or disables compatibility mode.
If enabled, setRecordingHint(boolean)
will always
be set to false
regardless of the current camera mode
.
enabled | set to true to enable compatibility mode |
---|
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()
.
flashMode | one of the supported flash mode defined in getFlashMode()
|
---|
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
.
cropMode | the crop mode to set in the leveler |
---|
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
.
orientation | the orientation used by the leveler when crop mode is set to
LOCKED . |
---|
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.
listener | the listener to set to HVTCamera |
---|
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.
frameSize | the frame size of the recorded movie |
---|
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);
rotation | the rotation of the screen in degrees as defined in getRotation() .
|
---|
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.
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 |
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
.
enabled | if true a watermark will be drawn
|
---|
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:
isStartingRecording()
and isRecording()
return true
.onRecordingHasStarted()
is
called, isStartingRecording()
turns false
and the actual recording takes place.
At this point, you may call stopRecording()
.Note: You must call this method only if isRunningIdle()
returns true
.
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() . |
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:
isStopped()
returns false
onStartedRunning(Camera.Parameters, int)
is called and isRunning()
turns true
. If it fails to start,
onFailedToStart()
is called. 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.
Requests to stop the recording process.
When this method is called the following events take place:
isStoppingRecording()
returns true
and onRecordingWillStop()
is called. onRecordingFinished(File, boolean)
is called, isStoppingRecording()
turns false
and isRecording()
turns false
. Note: You must call this method only if isRecording()
returns true
and after onRecordingHasStarted()
has been called.
Requests to stop the camera.
When the method is called, the following take place:
isRunning()
turns false
. HVTCamera is transitioning to a stopped state
asynchronously. onWillStopRunning()
is called.onStoppedRunning()
is called and
isStopped()
returns true
.If it is called while recording, it will internally call stopRecording()
and then
stopRunning()
.