Appendix - 6 / 6 -
Note
The BREW SimpleCamera application tutorial demonstrates the fundamentals of handling camera events and camera images with SophiaFramework UNIVERSE.
The class of interest here is the SFBCamera class, which is the SophiaFramework UNIVERSE wrapper for the BREW Icamera class.
* This appendix assumes readers have already gone through the HelloWorld tutorial and appendix.
Camera Class Overview
Camera Header File
-
Camera.hpp starts off by declaring an enum, StatusEnum, representing the different states of the application.
The type definition *NotifySPP, is for creating pointers to external callback functions.
Variable for the camera interface (Ex. SFBCameraSmp _sfbcamera), saving the bitmap (Ex. SFBBitmapSmp _camBitmap), saving the media data (Ex. ACharPtr _mimeType), etc are declared.
AfterSnapshot() is the function that is called to process a snapshot after it is taken.
Functions that change the state of the application (SFCError camPreview(), SFCError camRecord(), etc) are decleared, along with functions to manage resources (SFBBitmapSmpRef GetBitmap(),Void camTerminate(), etc).
A dummy callback handler OnCameraSHP() is declared along with its body function. And functions to get and set the different class variables are declared.
Camera Class Constructor
The Camera class constructor initializes several resource and state variables to NULL and False; since the camera is currently in a "standby" state.
It also initializes the AEEMediaData type variable _mediaData, with the media type (MMD_FILE_NAME), the image file name (camera.jpg) and the data size ("0"). An ACharPtr _mimeType is set to the file path "image/jpeg".
Camera Initialization
The first step of initialization is creating a bitmap with the SFXGraphics CreateBitmap() function, and saving it in _camBitmap.
If this bitmap is successfully created, the camResume() function is called, and assuming there is sufficient memory available to generate an instance of Camera, the Camera class's _camRect, _camSPP and _camReference member variables are set to the values of the given application variables.
For additional information concerning the camInitialize() function's arguments, click here.
Preview Mode
The camPreview() function first checks if an instance of the camera interface was obtained, _sfbcamera != null, and if so, it sets the _camStatus to STATUS_PREVIEW.
It then sets both the bools _camPreviewable and _camRecordable to false (meaning that the application cannot do anything yet), to ensure that no previewing events will be accepted before they are ready to be handled. The previewing camera is booted by calling the SFBCamera Preview() function.
Snaphot Mode
The record function is where the processing for taking a picture in the snapshot mode is coded.
camRecord() sets both the _camPreviewable and _camRecordable camera member variables to false (not allowing the application to preview or take snapshots).
The _camStatus is changed to STATUS_RECORD, and the SFBCamera Stop() function is invoked to end the preview mode. The Stop() function also generates the event CAM_STATUS_DONE.
For additional information concerning the camPreview() function, click here.
Suspending the Camera
The camSuspend() function sets the _camPreviewable and _camRecordable camera member variables to false, invokes the SFBCamera Stop() function and calls the SFBBase Release() function to act upon the camera.
Release() decrements the reference count of an object; the object is freed from memory and is no longer valid once its reference count reaches 0.
Resuming the Camera
The role of the camResume() function is to perform basic setup for the camera.
It creates a new instance of the camera interface and saves it in _sfbcamera. It sets _camPreviewable to TRUE, and _camRecordable to FALSE.
RegisterNotify() is a callback notification function from the ICamera class; it returns an SFCError indicating the result of registration.
The PICTURE_WITH and PICTURE_HEIGHT are set in the cx and cy components of the AEESize size variable. AEESize is a BREW structure used to specify size. size is then used as the argument to the SFBCamera SetSize() function, which sets up the camera to take a snapshot in the specified size.
The SFBCamera SetDisplaySize() function takes a reference to size as an argument, and sets the proportions of the frame to display the photo image.
If any errors occurred along the way, error != SFERR_NO_ERROR, the camSuspend() function is called to suspend the application.
Terminating the Camera
The camTerminate() function is called when either errors within the application have been detected, or when the applications needs to quit.
It calls the camSuspend() function, and checks to see if the _camBitmap still has memory. If so, the Release() function is called to act upon _camBitmap.
After a Snapshot
AfterSnapShot() is the function that is called when a picture has been taken in the snapshot mode, and needs to be saved as a bitmap.
It first gets the current frame captured by the camera through the SFBCamera GetFrame() function, and saves it as a bitmap.
The SFBBitmap BltIn() function is then used perform a bit-block transfer of a rectangle of pixels from bitmap into _camBitmap. BltIn() associates each source pixel with a corresponding destination pixel, and performs a logical operation on each pair. The internal callback _camSPP is called at the end.
OnCameraSHP & OnCamera
See Implement Camera Class [Internal Callback Function].
Get the Brightness
-
The current brightness of the camera is returned by the GetCamBrightness() function.
Two local variables are declared here, one to save the current brightness (SInt32 value), and one to save information concerning brightness (AEEParmInfo info).
The data itself is actually obtained through the SFBCamera GetParm() function. The arguments of this function are the parameter ID (CAM_PARM_BRIGHTNESS), a reference to save the current value and a reference to save general specifications information.
If it succeeds in obtaining the parameters, the brightness (value) is returned.
Get Range of Brightness
-
The range of brightness is determined in the GetCamBrightnessRange() function, but before trying to obtain the range, it should be verified that the device has brightness setting capabilities. This is done by the SFBCamera IsBrightness() function.
The result of the check is saved in the Boolean value support; if support is TRUE, the GetParm() function is once again called. This time, the minimum and maximum values of brightness, info.nMin and info.nMax, are assigned respectively to *minimum and *maximum.
Set the Brightness
The brightness can only be set if _camRecordable is TRUE. The SFBCamera SetBrightness() function is called to set the new brightness value.
Get Current Zoom Value
-
The GetCamZoom() function works in exactly the same way as the GetCamBrightness() function, except for the parameter ID argument of the GetParm() function which is now CAM_PARM_ZOOM.
Get the Zoom Range
-
The GetCamZoomRange() function is coded just like the GetCamBrightnessRange() function, the only difference being the parameter ID argument of the GetParm() function which is, in this case CAM_PARM_ZOOM.
Set the Zoom
The zoom value can only be set if _camRecordable is TRUE. The SFBCamera SetZoom() function is called to update the camera's zoom value.
SimpleCamera Class Overview
SimpleCamera Header File
The SimpleCamera class inherits from the SFCApplication class, meaning that it will not use the GUI Framework.
It declares a variable of the camera class (_camera) and a variable of the enum type AppStatus (_status) representing three states: STATUS_NONE, STATUS_PREVIEW and STATUS_SNAP.
Variables to save the different settings parameters are declared, along with a general event handler (Invoke()), and handler functions (OnAppStart(), OnKey(), etc).
Finally SimpleCamera's callback function and camera event handler, are declared along with various application specific functions.
Event Handling
Event Handler
The SimpleCamera event handler, Invoke(), handles three types of events: application start, application stop and key events.
If the event type is SFEVT_APP_START, it results in OnAppStart() being called, SFEVT_APP_STOP results in OnAppStop() being called, and SFEVT_KEY results in OnKey being called.
Application Start Up Handler Function
OnAppStart() initializes an instance of the Camera class by calling the camInitialize() function, whose parameters are the handset's rectangular screen coordinates, the CameraCallback function and a reference to itself.
If the initialization fails, an error message is printed.
Application End Handler Function
The handler function for the stop event, OnAppStop(), ends the SimpleCamera application by calling the Camera class camTerminate() function.
The Key Handler Function
-
The key handler OnKey() first checks to see if either the "Power" or the "End" keys have been pressed.
Definitions for handling these keys are not always explicitly written for each application, but they are in this case since both camera and bitmap resources need to be freed by the camera camTerminate() function, and then the SFCApplication Terminate() function.
Next, other key events are handled by nested switch statements. The outer layer's switch key is the _status. If the _status is STATUS_PREVIEW, the "Select" key takes a snapshot (Record()), the "Left" and "Right" keys change the brightness (ChangeBrightness()), and the "Up" and "Down" keys change the zoom level (ChangeZoom()).
If the _status is STATUS_SNAP, pressing any key returns to the preview mode by calling the PreviewCamera() function.
The default case is when the camera does not start, any key ends the application by calling the Terminate() function.
SimpleCamera Callback
Once again there are two parts to the callback, the CameraCallback function is just a dummy function that creates a SimpleCameraPtr p, and calls the real function OnSimpleCamera() through this pointer.
OnSimpleCamera() receives the status and the error information. If there is an error (error != SFERR_NO_ERROR), the camera instance is terminated and an error message is printed through the PrintError() function.
Else, if the status is STATUS_ENCODE, the status is changed to STATUS_SNAP and the DisplayImage() function is called.
The Preview Camera
If it is possible to preview (IsPreviewable()), PreviewCamera() calls the camPreview() function.
If it is not yet possible to start the preview, and _status is STATUS_NONE, the device's range of brightness and zoom are obtained and set using functions defined in the Camera class, and the _status is set to STATUS_PREVIEW.
Printing Error Messages
This function uses exactly the same techniques as those used in the Breakout ShowGameOver() function. ( See Breakout Appendix [ Show Game Over ] )
Display Picture Image
The picture image taken in snapshot mode, is displayed by first getting a reference to a graphics instance through the SFXGraphics GetInstance() function and saving it in the SFXGraphicsPtr pg.
A smart pointer to a bitmap ( displayBmp ), that it is to be displayed through the graphics instance pg, is created. The BltIn() function is then called to transfer each bit block of pixels from the source ( _camera.GetBitmap() ) to the destination displayBmp.
For the image to be actually visible on screen, the SFXGraphics Update() function needs to be called.
Change Brightness
ChangeBrightness() is called when either the "Left" or "Right" directional keys are pressed.
If its argument isBrighter is TRUE ( meaning the "Right" key was pressed), the _brightness is incremented through the SetCamBrightness() function. Otherwise, if it is still possible to reduce brightness, it is decremented in the same way.
Change Zoom
The ChangeZoom() function is coded in exactly the way as the ChangeBrightness function, substituting the brightness values and functions, for zoom ones.
