Data Structures | Macros | Typedefs | Enumerations | Functions
Camera.h File Reference

Detailed Description

Camera driver interface.


The Camera header file should be included in an application as follows:

Overview

The Camera driver is used to retrieve the data being transferred by the Camera sensor. This driver provides an API for capturing the image from the Camera sensor. The camera sensor control and implementation are the responsibility of the application using the interface.

The Camera driver has been designed to operate in an RTOS environment. It protects its transactions with OS primitives supplied by the underlying RTOS.

Usage

The Camera driver includes the following APIs:

Camera Driver Configuration

In order to use the Camera APIs, the application is required to provide device-specific Camera configuration in the Board.c file. The Camera driver interface defines a configuration data structure:

typedef struct Camera_Config_ {
void *object;
void const *hwAttrs;

The application must declare an array of Camera_Config elements, named Camera_config[]. Each element of Camera_config[] must be populated with pointers to a device specific Camera driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as the Camera peripheral's base address. Each element in Camera_config[] corresponds to a Camera instance, and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as Camera0 or Camera1). For example, it is possible to use Camera_config[0] for Camera1.

Because the Camera configuration is very device dependent, you will need to check the doxygen for the device specific Camera implementation. There you will find a description of the Camera hardware attributes. Please also refer to the Board.c file of any of your examples to see the Camera configuration.

Initializing the Camear Driver

The application initializes the Camera driver by calling Camera_init(). This function must be called before any other Camera API. Camera_init() iterates through the elements of the Camera_config[] array, calling the element's device implementation Camera initialization function.

Camera Parameters

The Camera_Params structure is passed to Camera_open(). If NULL is passed for the parameters, Camera_open() uses default parameters. A Camera_Params structure is initialized with default values by passing it to Camera_Params_init(). Some of the Camera parameters are described below. To see brief descriptions of all the parameters, see Camera_Params.

Camera Modes

The Camera driver operates in either blocking mode or callback mode:

The capture mode is determined by the Camera_Params.captureMode parameter passed to Camera_open(). The Camera driver defaults to blocking mode, if the application does not set it.

Once a Camera driver instance is opened, the only way to change the capture mode is to close and re-open the Camera instance with the new capture mode.

Opening the driver

The following example opens a Camera driver instance in blocking mode:

< Change any other params as required >
handle = Camera_open(someCamera_configIndexValue, &params);
if (!handle) {
// Error opening the Camera driver
}

Capturing an Image

The following code example captures a frame.

unsigned char captureBuffer[1920];
ret = Camera_capture(handle, &captureBuffer, sizeof(captureBuffer));

Implementation

This module serves as the main interface for RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a Camera_FxnTable.

The Camera driver interface module is joined (at link time) to an array of Camera_Config data structures named Camera_config. Camera_config is implemented in the application with each entry being an instance of a Camera peripheral. Each entry in Camera_config contains a:

#include <stdint.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures

struct  Camera_Params_
 Camera Parameters. More...
 
struct  Camera_FxnTable_
 The definition of a Camera function table that contains the required set of functions to control a specific Camera driver implementation. More...
 
struct  Camera_Config_
 Camera Global configuration. More...
 

Macros

#define CAMERA_CMD_RESERVED   (32)
 
#define CAMERA_STATUS_RESERVED   (-32)
 
#define CAMERA_STATUS_SUCCESS   (0)
 Successful status code returned by Camera_control(). More...
 
#define CAMERA_STATUS_ERROR   (-1)
 Generic error status code returned by Camera_control(). More...
 
#define CAMERA_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by Camera_control() for undefined command codes. More...
 
#define Camera_WAIT_FOREVER   (~(0U))
 Wait forever define. More...
 

Typedefs

typedef struct Camera_Config_Camera_Handle
 A handle that is returned from a Camera_open() call. More...
 
typedef void(* Camera_Callback) (Camera_Handle handle, void *buf, size_t frameLength)
 The definition of a callback function used by the Camera driver when used in Camera_MODE_CALLBACK. More...
 
typedef enum Camera_CaptureMode_ Camera_CaptureMode
 Camera capture mode settings. More...
 
typedef enum Camera_HSyncPolarity_ Camera_HSyncPolarity
 Camera HSync polarity. More...
 
typedef enum Camera_VSyncPolarity_ Camera_VSyncPolarity
 Camera VSync polarity. More...
 
typedef enum Camera_PixelClkConfig_ Camera_PixelClkConfig
 Camera pixel clock configuration. More...
 
typedef enum Camera_ByteOrder_ Camera_ByteOrder
 Camera byte order. More...
 
typedef enum Camera_IfSynchoronisation_ Camera_IfSynchoronisation
 Camera interface synchronization. More...
 
typedef enum Camera_StopCaptureConfig_ Camera_StopCaptureConfig
 Camera stop capture configuration. More...
 
typedef enum Camera_StartCaptureConfig_ Camera_StartCaptureConfig
 Camera start capture configuration. More...
 
typedef struct Camera_Params_ Camera_Params
 Camera Parameters. More...
 
typedef void(* Camera_CloseFxn) (Camera_Handle handle)
 A function pointer to a driver specific implementation of Camera_close(). More...
 
typedef int_fast16_t(* Camera_ControlFxn) (Camera_Handle handle, uint_fast16_t cmd, void *arg)
 A function pointer to a driver specific implementation of Camera_control(). More...
 
typedef void(* Camera_InitFxn) (Camera_Handle handle)
 A function pointer to a driver specific implementation of Camera_init(). More...
 
typedef Camera_Handle(* Camera_OpenFxn) (Camera_Handle handle, Camera_Params *params)
 A function pointer to a driver specific implementation of Camera_open(). More...
 
typedef int_fast16_t(* Camera_CaptureFxn) (Camera_Handle handle, void *buffer, size_t bufferlen, size_t *frameLen)
 A function pointer to a driver specific implementation of Camera_capture(). More...
 
typedef struct Camera_FxnTable_ Camera_FxnTable
 The definition of a Camera function table that contains the required set of functions to control a specific Camera driver implementation. More...
 
typedef struct Camera_Config_ Camera_Config
 Camera Global configuration. More...
 

Enumerations

enum  Camera_CaptureMode_ { Camera_MODE_BLOCKING, Camera_MODE_CALLBACK }
 Camera capture mode settings. More...
 
enum  Camera_HSyncPolarity_ { Camera_HSYNC_POLARITY_HIGH = 0, Camera_HSYNC_POLARITY_LOW }
 Camera HSync polarity. More...
 
enum  Camera_VSyncPolarity_ { Camera_VSYNC_POLARITY_HIGH = 0, Camera_VSYNC_POLARITY_LOW }
 Camera VSync polarity. More...
 
enum  Camera_PixelClkConfig_ { Camera_PCLK_CONFIG_RISING_EDGE = 0, Camera_PCLK_CONFIG_FALLING_EDGE }
 Camera pixel clock configuration. More...
 
enum  Camera_ByteOrder_ { Camera_BYTE_ORDER_NORMAL = 0, Camera_BYTE_ORDER_SWAP }
 Camera byte order. More...
 
enum  Camera_IfSynchoronisation_ { Camera_INTERFACE_SYNC_OFF = 0, Camera_INTERFACE_SYNC_ON }
 Camera interface synchronization. More...
 
enum  Camera_StopCaptureConfig_ { Camera_STOP_CAPTURE_IMMEDIATE = 0, Camera_STOP_CAPTURE_FRAME_END }
 Camera stop capture configuration. More...
 
enum  Camera_StartCaptureConfig_ { Camera_START_CAPTURE_IMMEDIATE = 0, Camera_START_CAPTURE_FRAME_START }
 Camera start capture configuration. More...
 

Functions

void Camera_close (Camera_Handle handle)
 Function to close a Camera peripheral specified by the Camera handle. More...
 
int_fast16_t Camera_control (Camera_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given Camera_Handle. More...
 
void Camera_init (void)
 Function to initializes the Camera module. More...
 
Camera_Handle Camera_open (uint_least8_t index, Camera_Params *params)
 Function to initialize a given Camera peripheral specified by the particular index value. The parameter specifies which mode the Camera will operate. More...
 
void Camera_Params_init (Camera_Params *params)
 Function to initialize the Camera_Params structure to its defaults. More...
 
int_fast16_t Camera_capture (Camera_Handle handle, void *buffer, size_t bufferlen, size_t *frameLen)
 Function that handles the Camera capture of a frame. More...
 

Macro Definition Documentation

§ Camera_WAIT_FOREVER

#define Camera_WAIT_FOREVER   (~(0U))

Wait forever define.

Typedef Documentation

§ Camera_Handle

typedef struct Camera_Config_* Camera_Handle

A handle that is returned from a Camera_open() call.

§ Camera_Callback

typedef void(* Camera_Callback) (Camera_Handle handle, void *buf, size_t frameLength)

The definition of a callback function used by the Camera driver when used in Camera_MODE_CALLBACK.

Parameters
Camera_HandleCamera_Handle
bufPointer to capture buffer
frameLengthlength of frame

§ Camera_CaptureMode

Camera capture mode settings.

This enum defines the capture mode for the configured Camera.

§ Camera_HSyncPolarity

Camera HSync polarity.

This enum defines the polarity of the HSync signal.

§ Camera_VSyncPolarity

Camera VSync polarity.

This enum defines the polarity of the VSync signal.

§ Camera_PixelClkConfig

Camera pixel clock configuration.

This enum defines the pixel clock configuration.

§ Camera_ByteOrder

Camera byte order.

This enum defines the byte order of camera capture.

In normal mode, the byte order is: | byte3 | byte2 | byte1 | byte0 |

In swap mode, the bytes are ordered as: | byte2 | byte3 | byte0 | byte1 |

§ Camera_IfSynchoronisation

Camera interface synchronization.

This enum defines the sensor to camera interface synchronization configuration.

§ Camera_StopCaptureConfig

Camera stop capture configuration.

This enum defines the stop capture configuration.

§ Camera_StartCaptureConfig

Camera start capture configuration.

This enum defines the start capture configuration.

§ Camera_Params

typedef struct Camera_Params_ Camera_Params

Camera Parameters.

Camera parameters are used to with the Camera_open() call. Default values for these parameters are set using Camera_Params_init().

If Camera_CaptureMode is set to Camera_MODE_BLOCKING then Camera_capture function calls will block thread execution until the capture has completed.

If Camera_CaptureMode is set to Camera_MODE_CALLBACK then Camera_capture will not block thread execution and it will call the function specified by captureCallbackFxn.

See also
Camera_Params_init()

§ Camera_CloseFxn

typedef void(* Camera_CloseFxn) (Camera_Handle handle)

A function pointer to a driver specific implementation of Camera_close().

§ Camera_ControlFxn

typedef int_fast16_t(* Camera_ControlFxn) (Camera_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of Camera_control().

§ Camera_InitFxn

typedef void(* Camera_InitFxn) (Camera_Handle handle)

A function pointer to a driver specific implementation of Camera_init().

§ Camera_OpenFxn

typedef Camera_Handle(* Camera_OpenFxn) (Camera_Handle handle, Camera_Params *params)

A function pointer to a driver specific implementation of Camera_open().

§ Camera_CaptureFxn

typedef int_fast16_t(* Camera_CaptureFxn) (Camera_Handle handle, void *buffer, size_t bufferlen, size_t *frameLen)

A function pointer to a driver specific implementation of Camera_capture().

§ Camera_FxnTable

The definition of a Camera function table that contains the required set of functions to control a specific Camera driver implementation.

§ Camera_Config

typedef struct Camera_Config_ Camera_Config

Camera Global configuration.

The Camera_Config structure contains a set of pointers used to characterize the Camera driver implementation.

This structure needs to be defined before calling Camera_init() and it must not be changed thereafter.

See also
Camera_init()

Enumeration Type Documentation

§ Camera_CaptureMode_

Camera capture mode settings.

This enum defines the capture mode for the configured Camera.

Enumerator
Camera_MODE_BLOCKING 

Uses a semaphore to block while data is being sent. Context of the call must be a Task.

Camera_MODE_CALLBACK 

Non-blocking and will return immediately. When the capture by the interrupt is finished the configured callback function is called.

§ Camera_HSyncPolarity_

Camera HSync polarity.

This enum defines the polarity of the HSync signal.

Enumerator
Camera_HSYNC_POLARITY_HIGH 
Camera_HSYNC_POLARITY_LOW 

§ Camera_VSyncPolarity_

Camera VSync polarity.

This enum defines the polarity of the VSync signal.

Enumerator
Camera_VSYNC_POLARITY_HIGH 
Camera_VSYNC_POLARITY_LOW 

§ Camera_PixelClkConfig_

Camera pixel clock configuration.

This enum defines the pixel clock configuration.

Enumerator
Camera_PCLK_CONFIG_RISING_EDGE 
Camera_PCLK_CONFIG_FALLING_EDGE 

§ Camera_ByteOrder_

Camera byte order.

This enum defines the byte order of camera capture.

In normal mode, the byte order is: | byte3 | byte2 | byte1 | byte0 |

In swap mode, the bytes are ordered as: | byte2 | byte3 | byte0 | byte1 |

Enumerator
Camera_BYTE_ORDER_NORMAL 
Camera_BYTE_ORDER_SWAP 

§ Camera_IfSynchoronisation_

Camera interface synchronization.

This enum defines the sensor to camera interface synchronization configuration.

Enumerator
Camera_INTERFACE_SYNC_OFF 
Camera_INTERFACE_SYNC_ON 

§ Camera_StopCaptureConfig_

Camera stop capture configuration.

This enum defines the stop capture configuration.

Enumerator
Camera_STOP_CAPTURE_IMMEDIATE 
Camera_STOP_CAPTURE_FRAME_END 

§ Camera_StartCaptureConfig_

Camera start capture configuration.

This enum defines the start capture configuration.

Enumerator
Camera_START_CAPTURE_IMMEDIATE 
Camera_START_CAPTURE_FRAME_START 

Function Documentation

§ Camera_close()

void Camera_close ( Camera_Handle  handle)

Function to close a Camera peripheral specified by the Camera handle.

Precondition
Camera_open() had to be called first.
Parameters
handleA Camera_Handle returned from Camera_open
See also
Camera_open()

§ Camera_control()

int_fast16_t Camera_control ( Camera_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given Camera_Handle.

Commands for Camera_control can originate from Camera.h or from implementation specific Camera*.h (CameraCC32XX.h, etc.. ) files. While commands from Camera.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific Camera*.h files add unique driver capabilities but are not API portable across all Camera driver implementations.

Commands supported by Camera.h follow a Camera_CMD_<cmd> naming convention.
Commands supported by Camera*.h follow a Camera*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See Camera_control command codes for command codes.

See Camera_control return status codes for status codes.

Precondition
Camera_open() has to be called first.
Parameters
handleA Camera handle returned from Camera_open()
cmdCamera.h or Camera*.h commands.
argAn optional R/W (read/write) command argument accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
See also
Camera_open()

§ Camera_init()

void Camera_init ( void  )

Function to initializes the Camera module.

Precondition
The Camera_config structure must exist and be persistent before this function can be called. This function must also be called before any other Camera driver APIs. This function call does not modify any peripheral registers.

§ Camera_open()

Camera_Handle Camera_open ( uint_least8_t  index,
Camera_Params params 
)

Function to initialize a given Camera peripheral specified by the particular index value. The parameter specifies which mode the Camera will operate.

Precondition
Camera controller has been initialized
Parameters
indexLogical peripheral number for the Camera indexed into the Camera_config table
paramsPointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).
Returns
A Camera_Handle on success or a NULL on an error or if it has been opened already.
See also
Camera_init()
Camera_close()

§ Camera_Params_init()

void Camera_Params_init ( Camera_Params params)

Function to initialize the Camera_Params structure to its defaults.

Parameters
paramsAn pointer to Camera_Params structure for initialization

Defaults values are: captureMode = Camera_MODE_BLOCKING; outputClock = 24000000; hsyncPolarity = Camera_HSYNC_POLARITY_HIGH; vsyncPolarity = Camera_VSYNC_POLARITY_HIGH; pixelClkConfig = Camera_PCLK_CONFIG_RISING_EDGE; byteOrder = Camera_BYTE_ORDER_NORMAL; interfaceSync = Camera_INTERFACE_SYNC_ON; stopConfig = Camera_STOP_CAPTURE_FRAME_END; startConfig = Camera_START_CAPTURE_FRAME_START; captureTimeout = Camera_WAIT_FOREVER; captureCallback = NULL;

§ Camera_capture()

int_fast16_t Camera_capture ( Camera_Handle  handle,
void *  buffer,
size_t  bufferlen,
size_t *  frameLen 
)

Function that handles the Camera capture of a frame.

In Camera_MODE_BLOCKING, Camera_capture will block task execution until the capture is complete.

In Camera_MODE_CALLBACK, Camera_capture does not block task execution and calls a callback function specified by captureCallbackFxn. The Camera buffer must stay persistent until the Camera_capture function has completed!

Parameters
handleA Camera_Handle
bufferA pointer to a WO (write-only) buffer into which the captured frame is placed
bufferlenLength (in bytes) of the capture buffer
frameLenPointer to return number of bytes captured.
Returns
CAMERA_STATUS_SUCCESS on successful capture, CAMERA_STATUS_ERROR if if otherwise.
See also
Camera_open
Copyright 2017, Texas Instruments Incorporated