en_US/camera/how_to_use_camera.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows">
<META http-equiv="Content-Style-Type" content="text/css">
<TITLE>How to Use the Camera Library: Overview</TITLE>
<LINK rel="stylesheet" href="../css/nitro.css" type="text/css">
</HEAD>
<BODY>
<H1 align="left">How to Use the Camera Library: Overview</H1>
<P>
This document gives notes related to using the cameras with the camera library.
</P>

<p><h2>How to Get Camera Images</h2></p>
<p>
A new DMA is used to get images taken by the camera.<font color="red">As a result, note that if the AHB bus is accessed with a higher priority than the DMA used by the camera, such as when a DMA is used elsewhere while the camera is still capturing, camera images may not be transferred in time, and a buffer error may occur.</font><br> <br>In general, the following steps are used to start capturing with the camera.
</p>
<ol>
<li>Start the capture with the <a href="CAMERA_DmaRecvAsync.html"><CODE>CAMERA_DmaRecvAsync</CODE></a> function and prepare for a new DMA transfer.
<li>Use the <a href="CAMERA_ClearBuffer.html"><CODE>CAMERA_ClearBuffer</CODE></a> function to clear the internal camera buffers.
<li>Use the <a href="CAMERA_I2CActivate.html"><CODE>CAMERA_I2CActivate</CODE></a> function to start the inner or outer camera.
<li>Use the <a href="CAMERA_StartCapture.html"><CODE>CAMERA_StartCapture</CODE></a> or <a href="CAMERA_Start.html"><CODE>CAMERA_Start</CODE></a> function to start capturing.
</ol>
<p>
Step 3 may be called before steps 1 or 2.<br><br> In the <a href="CAMERA_DmaRecvAsync.html"><CODE>CAMERA_DmaRecvAsync</CODE></a> function, the completion callback is invoked when all data (the image for a single frame) is finished being transferred. The callback function must therefore call the <a href="CAMERA_DmaRecvAsync.html"><CODE>CAMERA_DmaRecvAsync</CODE></a> function in the same way to get the image for the next frame.
</p>

<H3>Example</H3>
<BLOCKQUOTE style="background-color:#ffffd0;"><CODE>void CameraDmaRecvIntr(void* arg)<br> {<br> CAMERA_DmaRecvAsync(... CameraDmaRecvIntr, NULL);<br> }<br> <br> ...<br> <br> CAMERA_DmaRecvAsync(... CameraDmaRecvIntr, NULL);<br> CAMERA_ClearBuffer();<br> CAMERA_StartCapture();<br></CODE></BLOCKQUOTE>

<p>
The callback specified by the <a href="CAMERA_SetBufferErrorCallback.html"><CODE>CAMERA_SetBufferErrorCallback</CODE></a> function is invoked if the camera image is not transferred in time and a buffer error occurs. To recover from a buffer error when one occurs, you must stop capturing, stop the new DMA that was in use, and then start capturing again.
</p>

<H3>Example</H3>
<BLOCKQUOTE style="background-color:#ffffd0;"><CODE>void CameraIntrError(CAMERAResult result)<br> {<br> CAMERA_StopCapture();<br> MI_StopNDma(...);<br> CAMERA_DmaRecvAsync(...);<br> CAMERA_ClearBuffer();<br> CAMERA_StartCapture();<br> }<br> <br> ...<br> <br> CAMERA_SetBufferErrorCallback(CameraIntrError);<br></CODE></BLOCKQUOTE>


<p><h2>Changing the Camera Settings</h2></p>
<p>
Only one camera configuration function can be called at once. Therefore, if asynchronous camera configuration functions are called consecutively, the second function call fails.<br><br> Some configuration functions cannot be used while the camera is capturing. For specific function names, see the <a href="CAMERA_IsBusy.html"><CODE>CAMERA_IsBusy</CODE></a> function reference. To change parameters using these functions during a camera VSync, for example, the callback for the camera VSync interrupt must first call <a href="CAMERA_StopCapture.html"><CODE>CAMERA_StopCapture</CODE></a>, followed by <CODE>CAMERA_SetXXX</CODE>, and finally <a href="CAMERA_StartCapture.html"><CODE>CAMERA_StartCapture</CODE></a>.
</p>

<p><h2>Difference Between Resolution and Trimming</h2></p>
<p>
Consider the following images: one has been trimmed to 256x192 using a function such as <a href="CAMERA_SetTrimmingParamsCenter.html"><CODE>CAMERA_SetTrimmingParamsCenter</CODE></a> after <a href="CAMERASize.html"><CODE>CAMERA_SIZE_VGA</CODE></a> has been specified to the <a href="CAMERA_I2CSize.html"><CODE>CAMERA_I2CSize</CODE></a> function, and the second has been obtained by specifying <a href="CAMERASize.html"><CODE>CAMERA_SIZE_DS_LCD</CODE></a> to the <a href="CAMERA_I2CSize.html"><CODE>CAMERA_I2CSize</CODE></a> function. There is no difference in processing load between these two images because they have the same size and consequently cause the same amount of data to be transferred by a new DMA. However, the smaller-size image after trimming and the smaller-size image with a lower resolution have a different angle of view (field angle). Changing the camera resolution alone does not change the area captured in the image, but the captured area is smaller if trimming is used to reduce the image size.
</p>

<p><h2>Shutting Down the Camera</h2></p>
<p>
Even if the <a href="CAMERA_StopCapture.html"><CODE>CAMERA_StopCapture</CODE></a> function has been called and <a href="CAMERA_I2CActivate.html"><CODE>CAMERA_I2Activate(CAMERA_SELECT_NONE)</CODE></a> has been run, the <a href="CAMERA_IsBusy.html"><CODE>CAMERA_IsBusy</CODE></a> function returns <CODE>TRUE</CODE> when processing to shut down the camera is carried out in a certain order or at a particular timing. This does not pose a problem, though, because the <a href="CAMERA_IsBusy.html"><CODE>CAMERA_IsBusy</CODE></a> function will return <CODE>FALSE</CODE> if the inner or outer camera is enabled in this state.<br><br>To force the <a href="CAMERA_IsBusy.html"><CODE>CAMERA_IsBusy</CODE></a> function to return <CODE>FALSE</CODE> reliably, you must first call the <a href="CAMERA_StopCapture.html"><CODE>CAMERA_StopCapture</CODE></a> function, confirm that the <a href="CAMERA_IsBusy.html"><CODE>CAMERA_IsBusy</CODE></a> function returns <CODE>FALSE</CODE> and then run <a href="CAMERA_I2CActivate.html"><CODE>CAMERA_I2CActivate(CAMERA_SELECT_NONE)</CODE></a>.
</p>

<p><h2>Camera Processing After Recovering from Sleep Mode</h2></p>
<p>
The camera automatically enters a standby state, <a href="CAMERA_I2CActivate.html"><CODE>CAMERA_I2CActivate(CAMERA_SELECT_NONE)</CODE></a>, when it goes into sleep mode. To enable the camera after recovering from sleep, the application must call the <a href="CAMERA_I2CActivate.html"><CODE>CAMERA_I2CActivate</CODE></a> function or otherwise implement processing to do so.
</p>

<p><h2>Recovering from a Camera Malfunction</h2></p>
<p>
By the nature of its design, there is a danger that static electricity, mechanical impacts, and other damage may prevent the camera from getting image data. If one of these events occurs, the camera library automatically restarts. The callback function registered by <a href="CAMERA_SetRebootCallback.html"><CODE>CAMERA_SetRebootCallback</CODE></a> is called after the restart process is complete. Restart processing automatically restores camera settings to their state immediately before the restart, so there is no particular processing for the application to run.<br><br>A value of <a href="CAMERAResult.html"><CODE>CAMERA_ILLEGAL_STATUS</CODE></a> is returned if a camera function is run during a restart. If necessary, retry that function after the callback function set by the <a href="CAMERA_SetRebootCallback.html"><CODE>CAMERA_SetRebootCallback</CODE></a> function has been invoked.<br><br>If <a href="CAMERAResult.html"><CODE>CAMERA_RESULT_FATAL_ERROR</CODE></a> is given as an argument to the callback function, it indicates that the restart process has failed and the camera may be physically damaged.<br>However, you may be able to recover the camera by switching the power off and on, so we recommend that you display a message to this effect to the user.<br>Show a message like the one below and do not proceed with any further processes with the DSi camera.<br><I>An error has occurred.</I><I>Press POWER on the DSi to turn the power off and then follow the instructions in the User Guide.</I>
</p>

<H2>See Also</H2>
<P><A href="list_camera.html">CAMERA Function List</A></P>
<H2>Revision History</H2>
<P>
2009/01/06 Added explanation of what to do when <CODE>CAMERA_RESULT_FATAL_ERROR</CODE> occurs.<br> 2009/01/05 Revised <B>Description</B> to get point across better.<br> 2008/09/11 Initial version.
</P>
<hr><p>CONFIDENTIAL</p></body>
</HTML>