API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

ICAMERA

Brew Release
Brew MP 1.0.2
See Also
IBitmap IDISPLAY
Description


ICamera interface provides a generic way to BREW applications to control a device camera and to record snapshots and movies in various formats like JPEG, MPEG4, and so forth. ICamera is a privileged class. You need to specify the class ID in the MIF.
Usage

Event Notification:


ICamera asynchronously notifies all the events to client app via the callback function. The app must register a callback notification function using ICAMERA_RegisterNotify().

Display:


When CAM_PARM_LCD_DIRECT_ACCESS is enabled, the lower layers will display the frames to the screen. The position of the image on the screen will be determined by the AEESize value that was configured when enabling CAM_PARM_LCD_DIRECT_ACCESS. The width and height of the image will be determined by the configured CAM_PARM_DISPLAY_SIZE. Other screen manipulations to this area of the screen may cause flickering due to multiple sources writting to the same area of the screen.
When CAM_PARM_LCD_DIRECT_ACCESS is not enabled, it is the application's responsibility to display frames to the screen. ICamera notifies the application of the new raw captured frame via user-registered callback function and use of the status CAM_STATUS_FRAME. To retrieve the raw frame, represented by IBitmap, the application needs to call ICAMERA_GetFrame() The orientation (portrait vs landscape) can be determined by calling IBitmap_GetInfo().
It is app's responsibility to display these frames to the screen or other destination.

Return Values:

Some ICamera functions may be synchronous and asynchronous depending on the values passed in, others are always synchronous or asychronous; check API documentation. If a function is always asynchronous a return value of SUCCESS means the command was accepted. Otherwuse a return value of SUCCESS means that the operation was synchronous and the operation was completed successfully. If a function is synchronous or asychronous depending on the input values, it will always return CAM_PENDING for asynchronous operations, and other error codes for synchronous operations.
An asynchronous function initiates an action and returns control to the application. The callback notifier function is called for a command with the status contained in the AEECameraNotify structure. An asynchronous operation is complete when the callback function's nStatus is equal to CAM_STATUS_DONE.
SUCCESS: Successful. Synchronous operation completed. OR SUCCESS: Asynchronous command accepted. Check callback for result and completion.
CAM_PENDING: Asynchronous Operation. Result is passed back to the application via the registered callback EBADPARM: Bad parameter is passed ENOMEMORY: Not enough memory EBADSTATE: Cannot execute operation because the camera is in the wrong mode. EUNSUPPORTED: Parameter is not supported EFAILED: General failure

App Suspend/Resume:


When the app gets EVT_APP_SUSPEND, it is recommended that the app stop the camera and release the ICamera interface. When the app gets EVT_APP_RESUME, it can create ICamera interface and resume its operation.

Sample Code:


Multiple Camera (sensor) support:

Each camera sensor is identified by ICamera CLSID. AEECamera.bid defines a list of CLSIDs with each CLSID identifying a sensor. AEECLSID_CAMERA is the same as AEECLSID_CAMERA1, which represents the default (primary) sensor. If the device has two cameras, then the second sensor is identified using AEECLSID_CAMERA2 and so on.
Some device implementations may not support multiple sensors at the same time (simultaneously). This means you cannot create ICamera instances corresponding to each of the sensors at the same time. Typically, ISHELL_CreateInstance() would return ENOTALLOWED if multiple sensors are not supported simultaneously.
   The following code snippet starts the camera in preview mode and displays frames to the device
   screen.  The preview should be stopped using additional code to call ICAMERA_Stop().

      static int CApp_StartCameraInPreviewMode(CApp * pme)
      {
         int   nErr;

         // Create ICamera instance.
         nErr = ISHELL_CreateInstance(pme->a.m_pIShell, AEECLSID_CAMERA, (void **)&pme->m_pICamera);
         if (nErr)
            return nErr;

         // Register callback notification function.
         nErr = ICAMERA_RegisterNotify(pme->m_pICamera, CApp_CameraNotify, pme);
         if (nErr)
            return nErr;

         ICAMERA_SetDisplaySize(pme->m_pICamera, &pme->m_sizePreview);
         ICAMERA_SetSize( m_pICamera, &pme->m_sizeFrame);
         nErr = ICAMERA_Preview(pme->m_pICamera);
         if (nErr)
            return nErr;

         return SUCCESS;
      }

      static void CApp_CameraNotify(void * pUser, AEECameraNotify * pn)
      {
         CApp *   pme = (CApp *)pUser;

         if (!pme || !pn)
            return;

         switch (pn->nStatus)
         {
            case CAM_STATUS_START:
               // Preview has begun...
               break;

            case CAM_STATUS_FRAME:
            {
               IBitmap *      pRawFrame;
               AEEBitmapInfo  bi;

               //
               // IMPORTANT NOTE: You need to do IBITMAP_Release(pRawFrame) after you're done with pRawFrame.
               //
               if (SUCCESS != ICAMERA_GetFrame(pme->m_pICamera, &pRawFrame))
                  return;

               // Get the bitmap info...this can be saved in app global structure.
               IBITMAP_GetInfo(pRawFrame, &bi, sizeof(bi));

               // Display the raw frame at (0, 0) location of the screen
               IDISPLAY_BitBlt(pme, 0, 0, bi.cx, bi.cy, pRawFrame, 0, 0, AEE_RO_COPY);
               IBITMAP_Release(pRawFrame);
               break;
            }

            case CAM_STATUS_DONE:
               // ICAMERA_Stop() was called and previous operation stopped.
               // The mode is Ready, and if everything is setup, ICAMERA_Preview(), 
               //     ICAMERA_RecordMovie() or ICAMERA_RecordSnapshot(), can be called.
               break;

            case CAM_STATUS_ABORT:
               // Preview got aborted.
               break;
         }
      }

Camera State Machine:


             ---------------------------READY-----------------------
            |      ^                   |    ^                |     ^
   Preview()|      |   RecordSnapshot()|    |   RecordMovie()|     |
            |      |                   |    |                |     |Stop()
            |      |Stop()             |    |                |     |
            V      |                   V    |                V     |
            PREVIEW                    SNAPSHOT               MOVIE
             |   ^                                            |   ^
             |   |                                            |   |
              ---                                              ---
             Pause()                                           Pause()
             Resume()                                          Resume()

Camera Modes:


ICamera has four modes: Ready, Preview, Snapshot and Movie. These modes are a state machine. The current mode can be retrieved by calling the ICAMERA_GetMode() function.
ICamera starts in the Ready mode, and can transition to the any other mode. The Preview, Snapshot, and Movie modes can only transition to the Ready mode. As an example, to transition from the Preview mode to the Movie mode, the camera must transition from the Preview mode to the Ready mode by calling ICAMERA_STOP(), waiting for the callback, and then transition from the Ready mode to the Movie mode by calling ICAMERA_RecordMovie(). All state transitions are asynchronous and are not completed until the callback notifier function is called for this command with the correct values in the AEECameraNotify structure.
See Camera State Machine:

Preview Mode:


Before you start the camera in preview mode, you need to perform the following operations: (1) ICAMERA_SetDisplaySize() to set the frame display size (2) [Optional] ICAMERA_SetFramesPerSecond() to set the FPS of the camera (3) If the mode is not CAM_MODE_READY, call ICAMERA_Stop() to start the camera's transition into CAM_MODE_READY and wait for the callback.
ICAMERA_Preview() starts the camera in preview mode. CAM_STATUS_START callback will be sent to the app. See display documentation for displaying the preview to the screen. ICAMERA_Pause() stops the preview. ICAMERA_Resume resumes the preview. ICAMERA_Stop() stops the preview operation and puts the camera in ready mode. CAM_STATUS_DONE callback will be sent to the app.
Note: It is recommended that atleast two frames be captured so that the camera sensor can adjust to the lighting conditions, before a snapshot it taken.

Snapshot Mode:


Before you do snapshot operation, you need to perform the following operations: (1) ICAMERA_SetMediaData() (2) ICAMERA_SetSize() (3) [Optional] ICAMERA_SetVideoEncode() (4) [Optional] ICAMERA_SetQuality() or ICAMERA_SetMaxFileSize() (5) [Optional] ICAMERA_SetFramesPerSecond() (6) If the mode is not CAM_MODE_READY, call ICAMERA_Stop() to start the camera's transition into CAM_MODE_READY and wait for the callback.
ICAMERA_RecordSnapshot() starts the snapshot recording operation. CAM_STATUS_START callback will be sent to app followed by CAM_STATUS_DONE when recording is complete. When the encoding is completed, {CAM_CMD_ENCODESNAPSHOT, CAM_STATUS_DONE} callback will be sent. When MaxFileSize and Quality are both set, whichever is set last will take effect.
ICamera can be configured to defer the snapshot encoding as follows. This is known as DeferEncode feature. Note that, by default, DeferEncode is disabled. (1) ICAMERA_SetMediaData() (2) ICAMERA_DeferEncode(TRUE): Indicates that encoding must be deferred
ICAMERA_RecordSnapshot() starts the snapshot recording operation. CAM_STATUS_START callback will be sent to app followed by CAM_STATUS_DONE when recording is complete. Now, only raw frame is recorded and it is not yet encoded. App can access the raw frame using ICAMERA_GetFrame() in the callback. ICAMERA_EncodeSnapshot() encodes the raw frame and sends {CAM_CMD_ENCODESNAPSHOT, CAM_STATUS_DONE} callback when encoding is done. Do ICAMERA_SetMediaData() before calling ICAMERA_EncodeSnapshot.
Note: It is recommended that atleast two frames be captured so that the camera sensor can adjust to the lighting conditions, before a snapshot it taken. If the camera never enters the preview or movie mode before encoding a snapshot the image may be all black or white because the camera sensor has not adjusted to the lighting conditions.

Movie Mode:


Before you do start recording movie, you need to perform the following operations: (1) ICAMERA_SetMediaData() (2) ICAMERA_SetSize() (3) [Optional] ICAMERA_SetVideoEncode() and ICAMERA_SetAudioEncode() (4) [Optional] ICAMERA_SetQuality() (5) [Optional] ICAMERA_SetBitRate() (6) [Optional] ICAMERA_SetFramesPerSecond() (7) If the mode is not CAM_MODE_READY, call ICAMERA_Stop() to start the camera's transition into CAM_MODE_READY and wait for the callback.
See display documentation for displaying the preview to the screen. ICAMERA_Pause() pauses recording. ICAMERA_Resume resumes the recording. ICAMERA_Stop() stops the record operation and puts the camera in ready mode. CAM_STATUS_DONE callback will be sent to app.
Note: It is recommended that atleast two frames be captured so that the camera sensor can adjust to the lighting conditions, before a snapshot it taken. If the camera never enters the preview or movie mode before encoding a snapshot the image may be all black or white because the camera sensor has not adjusted to the lighting conditions.


Camera Call Flow:

[ICamera Mode]  BREW App                      BREW ICamera           Example OEM Camera Layer
---------------------------------------------------------------------------------------
(1) Preview:
-----------
                     ------ICAMERA_SetDisplaySize()--------->

[READY]              ------ICAMERA_Preview()--------->
                                                      -------camera_start_preview()->

[PREVIEW]                                             <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_START-----------

                                                      <-------FRAME-------------------
                     <-----CAM_CMD_START/CAM_STATUS_FRAME---
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]

                                                      <-------FRAME-------------------
                     <-----CAM_CMD_START/CAM_STATUS_FRAME---
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]
                              :
                              :
                              :
                     ------ICAMERA_Stop()------------>
                                                      -------camera_stop_preview()-->

[READY]                                               <-------DONE-------------------
                     <-----CAM_CMD_START/CAM_STATUS_DONE------------
 
(2) Preview (CAM_PARM_LCD_DIRECT_ACCESS enabled):
-----------
                     ------ICAMERA_SetDisplaySize()--------->

[READY]              ------ICAMERA_Preview()--------->
                                                      -------camera_start_preview()->

[PREVIEW]                                             <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_START-----------
                              :
                              :
                              :
                     ------ICAMERA_Stop()------------>
                                                      -------camera_stop_preview()-->

[READY]                                               <-------DONE-------------------
                     <-----CAM_CMD_START/CAM_STATUS_DONE------------
 
 
(3) Record SnapShot (Immediate Encoding):
----------------------------------------
                     ------ICAMERA_SetMediaData()------->
                     ------ICAMERA_SetVideoEncode()---->
                     ------ICAMERA_SetSize()------->

                     ------[Optional]ICAMERA_SetQuality()------>

[READY]              ------ICAMERA_RecordSnapshot()-->
                                                      -------camera_take_picture()-->
                                                      <-------SUCCESS----------------
[SNAPSHOT]           <-----CAM_CMD_START/CAM_STATUS_START-----------
                                                      <-------DONE(SnapshotFrame)----
[READY]              <-----CAM_CMD_START/CAM_STATUS_DONE------------
                                                      -------camera_encode(SnapshotFrame)-->
                                                      <-------SUCCESS-------------

                                                      <-------DONE----------------
[READY]              <-----CAM_CMD_ENCODESNAPSHOT/CAM_STATUS_DONE------------

(4) Record SnapShot (Deferred Encoding):
---------------------------------------
                     ------ICAMERA_SetMediaData()------->
                     ------ICAMERA_SetVideoEncode()---->
                     ------ICAMERA_SetSize()------->
                     ------ICAMERA_SetQuality()------>

[READY]              ------ICAMERA_RecordSnapshot()-->
                                                      -------camera_take_picture()-->
                                                      <-------SUCCESS----------------
[SNAPSHOT]           <-----CAM_CMD_START/CAM_STATUS_START-----------
                                                      <-------DONE(SnapshotFrame)--
[READY]              <-----CAM_CMD_START/CAM_STATUS_DONE------------
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]

                     ------ICAMERA_EncodeSnapshot()-->
                                                      -------camera_encode(SnapshotFrame)-->
                                                      <-------SUCCESS-------------

                                                      <-------DONE----------------
[READY]              <-----CAM_CMD_ENCODESNAPSHOT/CAM_STATUS_DONE------------

(5) Record Movie:
----------------
                     ------ICAMERA_SetMediaData()------->
                     ------ICAMERA_SetVideoEncode()---->
                     ------ICAMERA_SetAudioEncode()---->
                     ------ICAMERA_SetSize()------->

                     ------[Optional]ICAMERA_SetQuality()------>
                     ------[Optional]ICAMERA_SetBitRate()------>
                     ------[Optional]ICAMERA_SetFramesPerSecond()------>

[READY]              ------ICAMERA_RecordMovie()----->
                                                      -------camera_start_record()->

[MOVIE]                                               <-------SUCCESS---------------
                     <-----CAM_CMD_START/CAM_STATUS_START-----------

                                                      <-------FRAME-------------------
                     <-----CAM_CMD_START/CAM_STATUS_FRAME---
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]

                                                      <-------FRAME-------------------
                     <-----CAM_CMD_START/CAM_STATUS_FRAME---
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]
                              :
                              :
                              :
                     ------ICAMERA_Pause()----------->
                                                      -------camera_pause_record()-->

                                                      <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_PAUSE-----------
                              :
                              :
                     ------ICAMERA_Resume()---------->
                                                      -----camera_resume_record()--->

                                                      <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_RESUME----------

                                                      <-------FRAME-------------------
                     <-----CAM_CMD_START/CAM_STATUS_FRAME---
                     ------ICAMERA_GetFrame()---------> [retrieves an IBitmap Frame]
                              :
                              :
                     ------ICAMERA_Stop()------------>
                                                      -------camera_stop_record()--->

[READY]                                               <-------DONE-------------------
                     <-----CAM_CMD_START/CAM_STATUS_DONE------------
(6) Record Movie(CAM_PARM_LCD_DIRECT_ACCESS enabled)::
----------------
                     ------ICAMERA_SetMediaData()------->
                     ------ICAMERA_SetVideoEncode()---->
                     ------ICAMERA_SetAudioEncode()---->
                     ------ICAMERA_SetSize()------->

                     ------[Optional]ICAMERA_SetQuality()------>
                     ------[Optional]ICAMERA_SetBitRate()------>
                     ------[Optional]ICAMERA_SetFramesPerSecond()------>

[READY]              ------ICAMERA_RecordMovie()----->
                                                      -------camera_start_record()->

[MOVIE]                                               <-------SUCCESS---------------
                     <-----CAM_CMD_START/CAM_STATUS_START-----------
                              :
                              :
                              :
                     ------ICAMERA_Pause()----------->
                                                      -------camera_pause_record()-->

                                                      <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_PAUSE-----------
                              :
                              :
                     ------ICAMERA_Resume()---------->
                                                      -----camera_resume_record()--->

                                                      <-------SUCCESS----------------
                     <-----CAM_CMD_START/CAM_STATUS_RESUME----------
                              :
                              :
                     ------ICAMERA_Stop()------------>
                                                      -------camera_stop_record()--->

[READY]                                               <-------DONE-------------------
                     <-----CAM_CMD_START/CAM_STATUS_DONE------------

(7) Setting Parameters (Synchronous operations):
----------------------------------------------------------------

[ANY]                ---ICAMERA_SetParm(CAM_PARM_XXX)-->
                                                      ---camera_set_parm(XXX)-->
                                                      <-------SUCCESS----------------

(8) Setting Parameters (Asynchronous operations):
----------------------------------------------------------------

[ANY]                ---ICAMERA_SetParm(CAM_PARM_XXX)-->
                                                      ---camera_set_parm(XXX)-->

                                                      <-------DONE--------------------
                     <-----CAM_CMD_SETPARM(CAM_PARM_XXX)/CAM_STATUS_DONE---

(9) Record MultiShot:
---------------------------------------

                     ------ICAMERA_SetSize()------->
                     
[READY]              ------ICAMERA_RecordMultiShot()-->
                     <-------SUCCESS----------------

[SNAPSHOT]           <-----CAM_CMD_START/CAM_MODE_SNAPSHOT/CAM_STATUS_START-----------
                                         [the camera will take a picture]
                     <-----CAM_CMD_START/CAM_MODE_SNAPSHOT/CAM_STATUS_FRAME-----------
                                          [the camera will take a picture]
                                :
                                :
 
 
    [optionally get the frames and display to screen]
                     ------ICAMERA_GetFrameByIndex()---------> [retrieves an 
                                                                IBitmap Frame]
                     ------IDISPLAY_BitBlt()--------->
                     ------IBITMAP_Release()--------->
 
                     <-----CAM_CMD_START/CAM_MODE_SNAPSHOT/CAM_STATUS_FRAME-----------
                                          [the camera will take a picture]
                                :
                                :

 
[READY]              <-----CAM_CMD_START/CAM_MODE_SNAPSHOT/CAM_STATUS_DONE-----------

                    
    [optionally encode the frames]
                     ------ICAMERA_SetMediaData()--------->
                     ------ICAMERA_EncodeByIndex()--------->

                    <-----CAM_CMD_ENCODE_SNAPSHOT/CAM_STATUS_DONE------------
    [optionally repeat encoding for other frames]