Camera.setMode() in Detail

Most cameras are capable of varying modes – including different widths and heights as well as different frame rates. By default Flash will use dimensions of 160 pixels X 120 pixels as well as 15 frames per second (fps) when connecting to a camera. However, you can programmatically specify the mode you want the camera to use with the setMode( ) method.

The setMode( ) method requires at least three parameters – the width, the height, and the frame rate of the requested camera mode. For example, the following code instructs Flash to attempt to set the mode of the camera associated with user_cam to 320 X 240 at 30fps.

user_cam.setMode(320, 240, 30);

While setMode( ) may seem fairly unassuming, it is actually rather complex. The reason for that is that each camera may have different native modes. That means that each camera is preconfigured with a set of modes at which it can operate, but different cameras may have different sets of modes. Therefore, it is possible that if you set the mode of a camera to 320 X 240 at 30fps, the actual result may differ slightly (or drastically.) In order to predict what kinds of behaviors setMode( ) can produce it can be helpful to understand the logic that it uses.

The setMode( ) method has some general rules that it follows. Specifically, setMode( ) cannot set the camera to a mode that exceeds the parameters passed to it. However, it can, if necessary, use a mode with smaller dimensions and/or a lower frame rate than the parameters passed to the method. The actual algorithms that the method uses are fairly complex. The basic process is as follows:

The preceding may seem overly complex. However, those steps enable you more flexibility in telling Flash how to select a compatible mode. The key is in the third step – the way in which Flash removes incompatible modes in three passes. The logic that Flash uses to remove those modes varies depending on what criteria is given priority. By default the frame rate is given priority. In that case the passes are as follows:

On the other hand, if area is given priority, the passes are as follows.

You can specify which criteria should be given priority using a fourth, optional parameter with the setMode( ) method. The fourth parameter should have a Boolean value – true if area should be given priority or false if frame rate should be given priority.

Although the theory is helpful, it's often most practical to see a few examples in order to best understand something. Let's look at a few example scenarios in order to see how setMode( ) works.

In some cases selecting whether the area or frame rate gets priority simply doesn't matter. Consider the following setMode( ) call.

user_cam.setMode(320, 240, 30, true);

In that case the following table represents a possible selection scenario.

Native modes First pass Second pass Third Pass Selection
 320, 288, 25  320, 288, 25  320, 288, 25    
512, 288, 13        
 80,  60, 30        
 160, 120, 30        
 320, 240, 25  320, 240, 25  320, 240, 25  320, 240, 25  320, 240, 25
 640, 480, 13        
 128,  96, 30        
 176, 144, 30        
 352, 288, 15  352, 288, 15      

In the example scenario even if frame rate is given priority, the actual selection remains the same.

user_cam.setMode(320, 240, 30, false);

The following table illustrates the passes and the actual selection. Even though the passes differ slightly from the preceding table, the actual selection is the same.

Native modes First pass Second pass Third Pass Selection
 320, 288, 25  320, 288, 25  320, 288, 25    
 512, 288, 13        
 80,  60, 30        
 160, 120, 30        
 320, 240, 25  320, 240, 25  320, 240, 25  320, 240, 25  320, 240, 25
 640, 480, 13        
 128,  96, 30        
 176, 144, 30        
 352, 288, 15  352, 288, 15      

However, sometimes the area/frame rate priority setting can have an effect. The following example illustrates how drastic the effect can be. The following example assumes the camera is the same (with the same native modes) as in the preceding examples. However, in this case setMode( ) is called to specify dimensions of 640 by 480. First, see what happens when area is given priority.

user_cam.setMode(640, 480, 30, true);

The following table illustrates the passes.

Native modes First pass Second pass Third Pass Selection
 320, 288, 25        
 512, 288, 13        
 80,  60, 30        
 160, 120, 30        
 320, 240, 25        
 640, 480, 13  640, 480, 13  640, 480, 13  640, 480, 13  640, 480, 13
 128,  96, 30        
 176, 144, 30        
 352, 288, 15        

On the other hand, the selection is very different if frame rate is given priority.

user_cam.setMode(640, 480, 30, false);

The table shows the passes given the preceding scenario.

Native modes First pass Second pass Third Pass Selection
 320, 288, 25  320, 288, 25  320, 288, 25  320, 288, 25  320, 288, 25
 512, 288, 13        
 80,  60, 30  80,  60, 30      
 160, 120, 30  160, 120, 30      
 320, 240, 25  320, 240, 25      
 640, 480, 13        
 128,  96, 30  128,  96, 30      
 176, 144, 30  176, 144, 30      
 352, 288, 15        

The preceding two example scenarios are only two of many possible ones.

You can retrieve the current mode settings using the width, height, and fps (read-only) properties of a Camera object. The fps property determines the maximum frame rate at which Flash will capture video using the device. However, it does not necessarily mean that it will always capture at that rate. If necessary, Flash will drop the frame rate in order to be able to continue to publish a stream given other settings and the amount of bandwidth available. You can retrieve the actual frame rate at any given point by reading the value from the (read-only) currentFps property.


Post or read comments for this page.


Document posted December 10, 2004 by Joey Lott
with thanks to Brad Edelman and Pritham Shetty who supplied much of the information reproduced here.

Updated March 3, 2005 to correct an error in the last example setMode() call. Thanks to Jayson K. Hanes for pointing it out.