Using the Camera View

The WZCameraView class provides a UI component for displaying a preview of the active camera.

Displaying the camera preview

The cameraView property of the WowzaGoCoder class is used to specify a previously created UIViewController-based view for the camera preview. The startPreview and stopPreview methods start and stop the camera preview display respectively.

//
// Demonstrates typical usage within the implementation of a UIViewController-based subclass
//
- (void) viewDidLoad {
   [super viewDidLoad];

   // ... view initialization code ...

    // Initialize the SDK
    [WowzaGoCoder registerLicenseKey:SDKSampleAppLicenseKey];
    self.goCoder = [WowzaGoCoder sharedInstance];

    // Assign the camera view
    self.goCoder.cameraView = self.view;

    // Start the camera preview
    self.goCoderCameraPreview = self.goCoder.cameraPreview;
    [self.goCoderCameraPreview startPreview];

    // ... addt'l view initialization code ...

The WZCameraView class is a subclass of the Android SDK's SurfaceView class and supports the standard set of View operations. It can also be used within an app's XML-based U/I layout definition to automatically create the camera view like so:

Example app layout file (e.g. app/res/layout/MainActivity.xml):

<!-- The root of the application layout -->
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:wowza="http://schemas.android.com/apk/res-auto"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    tools:context=".MainActivity">

    <!-- The camera preview display -->
    <com.wowza.gocoder.sdk.api.devices.WZCameraView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:id="@+id/cameraPreview"
        wowza:scaleMode="crop"
        wowza:defaultCamera="back"
        wowza:frameSizePreset="frameSize1280x720"/>

</RelativeLayout>

The WZCameraView view element supports a set of custom parameters for specifying the view's initial state:

Layout Parameter Description Values Default Value
scaleMode The preview scaling mode crop fill fill
defaultCamera The default camera to preview front back back
frameSizePreset A preset configuration identifier for the frame size frameSize320x240 frameSize640x480 frameSize960x540 frameSize1280x720 frameSize1920x1080 frameSize3840x2160 frameSize640x480

The setCameraView method is used to associate the camera view with the GoCoder SDK:

// Initialize the SDK
this.goCoder = WowzaGoCoder.init(this, SDK_SAMPLE_APP_LICENSE_KEY);

// Assign the camera view
this.goCoderCameraView = (WZCameraView) findViewById(R.id.cameraPreview);
this.goCoder.setCameraView(this.goCoderCameraView);

// Start the camera preview
this.goCoderCameraView.startPreview();

You can also create a camera view programmatically like so:

// Programmatically create and add the camera view
this.goCoderCameraView = new WZCameraView(this);

// Get the parent view and define the layout behavior
FrameLayout cameraViewContainer = (FrameLayout)findViewById(R.id.cameraView);
FrameLayout.LayoutParams layoutParams = new FrameLayout.LayoutParams(
        FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT);

// Add the camera view to the parent containing view
cameraViewContainer.addView(this.goCoderCameraView, layoutParams);

// Associate the camera view with the GoCoder SDK
this.goCoder.setCameraView(this.goCoderCameraView);

The startPreview and stopPreview methods start and stop the camera preview display respectively.


Detecting the cameras available

The cameras property is an array of WZCamera objects that can be used to access each of the device cameras.

// Enable the switch camera button if more than one camera is available
self.switchCameraButton.enabled = self.goCoderCameraPreview.cameras.count > 1;

The getNumberOfDeviceCameras static method returns the number of cameras available and the getCameras method returns an array of WZCamera objects for each.

// Enable the switch camera button if more than one camera is available
WZCamera[] cameras = this.goCoderCameraView.getCameras();
this.switchCameraButton.setEnabled(cameras.length > 1);

Setting the active camera

The active camera can be specified using the camera property and the switchCamera method can be used to the other camera (i.e. from front to back or vice versa) when applicable.

// Set the active camera to the front camera if it is not already active
if (self.goCoderCameraPreview.camera.direction != WZCameraDirectionFront)
    [self.goCoderCameraPreview.switchCamera];
}

The active camera is set with the setCamera method and the switchCamera method can be used to the other camera (i.e. from front to back or vice versa) when applicable.

// Set the active camera to the front camera if it is not already active
if (!this.goCoderCameraView.getCamera().isFront())
    WZCamera newCamera = this.goCoderCameraView.switchCamera();

Setting the preview frame size

The frame size for the camera preview is set with the config property.

If the active camera does not support the frame size specified, the closest supported frame size will be selected.

// Set the camera preview to 720p
WowzaConfig previewConfig = self.goCoderCameraPreview.config;
[previewConfig loadPreset:WZFrameSizePreset1280x720];
self.goCoderCameraPreview.config = previewConfig;

The frame size for the camera preview is set with the setFrameSize method.

If the active camera does not support the frame size specified, the closest supported frame size will be selected. The actual frame size used is returned from the setFrameSize method. The getSupportedFrameSizes of the WZCamera class can be used to determine the frame size supported for a particular camera.

// Set the camera preview to 720p
WZSize actualFrameSize = this.goCoderCameraView.setFrameSize(WZMediaConfig.FRAME_SIZE_1280x720);

Setting the crop and scale behavior

The previewGravity property is used to specify how the camera preview should be displayed when the active frame size and/or aspect ratio of the camera does not match that of the view. There are three modes available:

WZCameraPreviewGravityResizeAspect The camera preview is scaled to fit within the view surface. Letterboxing may be applied in order to maintain the proper aspect ratio.
WZCameraPreviewGravityResizeAspectFill The camera preview is scaled to fill the entire view surface. Some of the preview may be cropped in order to maintain the proper aspect ratio.
WZCameraPreviewGravityResize The camera preview will be stretched to fit entirely within the view surface.
// Set the cropping mode so that the full frame is displayed, potentially cropped
self.goCoderCameraPreview.previewGravity = WZCameraPreviewGravityResizeAspect;

The setScaleMode method is used to specify how the camera preview should be displayed when the active frame size and/or aspect ratio of the camera does not match that of the view. There are three modes available:

WZMediaConfig.CROP_TO_FRAME The camera preview is scaled to that is displayed in it's entirety within the view surface. Letterboxing may be applied in order to maintain the proper aspect ratio.
WZMediaConfig.FILL_FRAME The camera preview is scaled to fill the entire view surface. Some of the preview may be cropped in order to maintain the proper aspect ratio.
// Set the cropping mode so that the full frame is displayed, potentially cropped
this.goCoderCameraView.setScaleMode(WZMediaConfig.CROP_TO_FRAME);