Camera.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2016, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!*****************************************************************************
33  * @file Camera.h
34  *
35  * @brief Camera driver interface
36  *
37  * The Camera header file should be included in an application as follows:
38  * @code
39  * #include <ti/drivers/Camera.h>
40  * @endcode
41  *
42  * # Overview #
43  * The Camera driver is used to retrieve the data being transferred by the
44  * Camera sensor.
45  * This driver provides an API for capturing the image from the Camera sensor.
46  * The camera sensor control and implementation are the responsibility of the
47  * application using the interface.
48  *
49  * The Camera driver has been designed to operate in an RTOS environment. It
50  * protects its transactions with OS primitives supplied by the underlying
51  * RTOS.
52  *
53  * # Usage #
54  *
55  * The Camera driver includes the following APIs:
56  * - Camera_init(): Initialize the Camera driver.
57  * - Camera_Params_init(): Initialize a #Camera_Params structure with default
58  * vaules.
59  * - Camera_open(): Open an instance of the Camera driver.
60  * - Camera_control(): Performs implemenation-specific features on a given
61  * Camera peripheral.
62  * - Camera_capture(): Capture a frame.
63  * - Camera_close(): De-initialize a given Camera instance.
64  *
65  *
66  * ### Camera Driver Configuration #
67  *
68  * In order to use the Camera APIs, the application is required
69  * to provide device-specific Camera configuration in the Board.c file.
70  * The Camera driver interface defines a configuration data structure:
71  *
72  * @code
73  * typedef struct Camera_Config_ {
74  * Camera_FxnTable const *fxnTablePtr;
75  * void *object;
76  * void const *hwAttrs;
77  * } Camera_Config;
78  * @endcode
79  *
80  * The application must declare an array of Camera_Config elements, named
81  * Camera_config[]. Each element of Camera_config[] must be populated with
82  * pointers to a device specific Camera driver implementation's function
83  * table, driver object, and hardware attributes. The hardware attributes
84  * define properties such as the Camera peripheral's base address.
85  * Each element in Camera_config[] corresponds to
86  * a Camera instance, and none of the elements should have NULL pointers.
87  * There is no correlation between the index and the
88  * peripheral designation (such as Camera0 or Camera1). For example, it
89  * is possible to use Camera_config[0] for Camera1.
90  *
91  * Because the Camera configuration is very device dependent, you will need to
92  * check the doxygen for the device specific Camera implementation. There you
93  * will find a description of the Camera hardware attributes. Please also
94  * refer to the Board.c file of any of your examples to see the Camera
95  * configuration.
96  *
97  * ### Initializing the Camear Driver #
98  * The application initializes the Camera driver by calling Camera_init().
99  * This function must be called before any other Camera API. Camera_init()
100  * iterates through the elements of the Camera_config[] array, calling
101  * the element's device implementation Camera initialization function.
102  * ### Camera Parameters
103  *
104  * The #Camera_Params structure is passed to Camera_open(). If NULL
105  * is passed for the parameters, Camera_open() uses default parameters.
106  * A #Camera_Params structure is initialized with default values by passing
107  * it to Camera_Params_init().
108  * Some of the Camera parameters are described below. To see brief descriptions
109  * of all the parameters, see #Camera_Params.
110  *
111  * #### Camera Modes
112  * The Camera driver operates in either blocking mode or callback mode:
113  * - #Camera_MODE_BLOCKING: The call to Camera_capture() blocks until the
114  * capture has completed.
115  * - #Camera_MODE_CALLBACK: The call to Camera_capture() returns immediately.
116  * When the capture completes, the Camera driver will call a user-
117  * specified callback function.
118  *
119  * The capture mode is determined by the #Camera_Params.captureMode parameter
120  * passed to Camera_open(). The Camera driver defaults to blocking mode, if the
121  * application does not set it.
122  *
123  * Once a Camera driver instance is opened, the only way
124  * to change the capture mode is to close and re-open the Camera
125  * instance with the new capture mode.
126  *
127  * ### Opening the driver #
128  * The following example opens a Camera driver instance in blocking mode:
129  * @code
130  * Camera_Handle handle;
131  * Camera_Params params;
132  *
133  * Camera_Params_init(&params);
134  * params.captureMode = Camera_MODE_BLOCKING;
135  * < Change any other params as required >
136  *
137  * handle = Camera_open(someCamera_configIndexValue, &params);
138  * if (!handle) {
139  * // Error opening the Camera driver
140  * }
141  * @endcode
142  *
143  * ### Capturing an Image #
144  *
145  * The following code example captures a frame.
146  *
147  * @code
148  * unsigned char captureBuffer[1920];
149  *
150  * ret = Camera_capture(handle, &captureBuffer, sizeof(captureBuffer));
151  * @endcode
152  *
153  * # Implementation #
154  *
155  * This module serves as the main interface for RTOS
156  * applications. Its purpose is to redirect the module's APIs to specific
157  * peripheral implementations which are specified using a pointer to a
158  * #Camera_FxnTable.
159  *
160  * The Camera driver interface module is joined (at link time) to an
161  * array of #Camera_Config data structures named *Camera_config*.
162  * *Camera_config* is implemented in the application with each entry being an
163  * instance of a Camera peripheral. Each entry in *Camera_config* contains a:
164  * - (Camera_FxnTable *) to a set of functions that implement a Camera
165  * peripheral
166  * - (void *) data object that is associated with the Camera_FxnTable
167  * - (void *) hardware attributes that are associated to the Camera_FxnTable
168  *
169  *******************************************************************************
170  */
171 
172 #ifndef ti_drivers_Camera__include
173 #define ti_drivers_Camera__include
174 
175 #ifdef __cplusplus
176 extern "C" {
177 #endif
178 
179 #include <stdint.h>
180 #include <stddef.h>
181 
199 #define CAMERA_CMD_RESERVED (32)
200 
213 #define CAMERA_STATUS_RESERVED (-32)
214 
228 #define CAMERA_STATUS_SUCCESS (0)
229 
236 #define CAMERA_STATUS_ERROR (-1)
237 
245 #define CAMERA_STATUS_UNDEFINEDCMD (-2)
246 
256 /* Add Camera_CMD_<commands> here */
257 
265 #define Camera_WAIT_FOREVER (~(0U))
266 
271 
283 typedef void (*Camera_Callback) (Camera_Handle handle, void *buf,
284  size_t frameLength);
285 
292 typedef enum Camera_CaptureMode_ {
298 
306 
312 typedef enum Camera_HSyncPolarity_ {
316 
322 typedef enum Camera_VSyncPolarity_ {
326 
336 
348 typedef enum Camera_ByteOrder_ {
352 
363 
373 
383 
399 typedef struct Camera_Params_ {
401  Camera_CaptureMode captureMode;
402 
404  uint32_t outputClock;
405 
407  Camera_HSyncPolarity hsyncPolarity;
408 
410  Camera_VSyncPolarity vsyncPolarity;
411 
413  Camera_PixelClkConfig pixelClkConfig;
414 
416  Camera_ByteOrder byteOrder;
417 
419  Camera_IfSynchoronisation interfaceSync;
420 
422  Camera_StopCaptureConfig stopConfig;
423 
425  Camera_StartCaptureConfig startConfig;
426 
428  uint32_t captureTimeout;
429 
432 
434  void *custom;
435 } Camera_Params;
436 
441 typedef void (*Camera_CloseFxn) (Camera_Handle handle);
442 
447 typedef int_fast16_t (*Camera_ControlFxn) (Camera_Handle handle,
448  uint_fast16_t cmd,
449  void *arg);
450 
455 typedef void (*Camera_InitFxn) (Camera_Handle handle);
456 
461 typedef Camera_Handle (*Camera_OpenFxn) (Camera_Handle handle,
462  Camera_Params *params);
463 
468 typedef int_fast16_t (*Camera_CaptureFxn) (Camera_Handle handle, void *buffer,
469  size_t bufferlen, size_t *frameLen);
470 
476 typedef struct Camera_FxnTable_ {
479 
482 
485 
488 
492 
504 typedef struct Camera_Config_ {
507 
509  void *object;
510 
512  void const *hwAttrs;
513 } Camera_Config;
514 
524 extern void Camera_close(Camera_Handle handle);
525 
563 extern int_fast16_t Camera_control(Camera_Handle handle, uint_fast16_t cmd,
564  void *arg);
565 
574 extern void Camera_init(void);
575 
596 extern Camera_Handle Camera_open(uint_least8_t index, Camera_Params *params);
597 
617 extern void Camera_Params_init(Camera_Params *params);
618 
644 extern int_fast16_t Camera_capture(Camera_Handle handle, void *buffer,
645  size_t bufferlen, size_t *frameLen);
646 
647 #ifdef __cplusplus
648 }
649 #endif
650 
651 #endif /* ti_drivers_Camera__include */
Definition: Camera.h:370
Camera_StartCaptureConfig startConfig
Definition: Camera.h:425
Camera_StopCaptureConfig_
Camera stop capture configuration.
Definition: Camera.h:369
Camera_CloseFxn closeFxn
Definition: Camera.h:478
uint32_t captureTimeout
Definition: Camera.h:428
void * object
Definition: Camera.h:509
Camera_HSyncPolarity hsyncPolarity
Definition: Camera.h:407
Camera_StartCaptureConfig_
Camera start capture configuration.
Definition: Camera.h:379
Definition: Camera.h:297
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().
Definition: Camera.h:447
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.
Definition: Camera.h:283
Camera_VSyncPolarity vsyncPolarity
Definition: Camera.h:410
Camera_VSyncPolarity_
Camera VSync polarity.
Definition: Camera.h:322
struct Camera_Config_ * Camera_Handle
A handle that is returned from a Camera_open() call.
Definition: Camera.h:270
Definition: Camera.h:380
Camera_PixelClkConfig_
Camera pixel clock configuration.
Definition: Camera.h:332
struct Camera_Params_ Camera_Params
Camera Parameters.
void Camera_init(void)
Function to initializes the Camera module.
Camera_OpenFxn openFxn
Definition: Camera.h:487
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.
void(* Camera_InitFxn)(Camera_Handle handle)
A function pointer to a driver specific implementation of Camera_init().
Definition: Camera.h:455
struct Camera_FxnTable_ Camera_FxnTable
The definition of a Camera function table that contains the required set of functions to control a sp...
Camera_Handle Camera_open(uint_least8_t index, Camera_Params *params)
Function to initialize a given Camera peripheral specified by the particular index value...
Definition: Camera.h:381
void Camera_Params_init(Camera_Params *params)
Function to initialize the Camera_Params structure to its defaults.
Camera_CaptureMode_
Camera capture mode settings.
Definition: Camera.h:292
enum Camera_CaptureMode_ Camera_CaptureMode
Camera capture mode settings.
void(* Camera_CloseFxn)(Camera_Handle handle)
A function pointer to a driver specific implementation of Camera_close().
Definition: Camera.h:441
Definition: Camera.h:360
Definition: Camera.h:324
Camera_Handle(* Camera_OpenFxn)(Camera_Handle handle, Camera_Params *params)
A function pointer to a driver specific implementation of Camera_open().
Definition: Camera.h:461
The definition of a Camera function table that contains the required set of functions to control a sp...
Definition: Camera.h:476
enum Camera_StopCaptureConfig_ Camera_StopCaptureConfig
Camera stop capture configuration.
Camera_InitFxn initFxn
Definition: Camera.h:484
Definition: Camera.h:304
void Camera_close(Camera_Handle handle)
Function to close a Camera peripheral specified by the Camera handle.
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().
Definition: Camera.h:468
uint32_t outputClock
Definition: Camera.h:404
Definition: Camera.h:314
Camera_CaptureFxn captureFxn
Definition: Camera.h:490
enum Camera_StartCaptureConfig_ Camera_StartCaptureConfig
Camera start capture configuration.
void * custom
Definition: Camera.h:434
enum Camera_HSyncPolarity_ Camera_HSyncPolarity
Camera HSync polarity.
Definition: Camera.h:361
Definition: Camera.h:334
Camera_StopCaptureConfig stopConfig
Definition: Camera.h:422
struct Camera_Config_ Camera_Config
Camera Global configuration.
Definition: Camera.h:350
Camera_Callback captureCallback
Definition: Camera.h:431
Camera_HSyncPolarity_
Camera HSync polarity.
Definition: Camera.h:312
int_fast16_t Camera_control(Camera_Handle handle, uint_fast16_t cmd, void *arg)
Function performs implementation specific features on a given Camera_Handle.
enum Camera_ByteOrder_ Camera_ByteOrder
Camera byte order.
enum Camera_PixelClkConfig_ Camera_PixelClkConfig
Camera pixel clock configuration.
Camera_PixelClkConfig pixelClkConfig
Definition: Camera.h:413
enum Camera_IfSynchoronisation_ Camera_IfSynchoronisation
Camera interface synchronization.
Camera_ByteOrder_
Camera byte order.
Definition: Camera.h:348
Definition: Camera.h:313
Camera_FxnTable const * fxnTablePtr
Definition: Camera.h:506
enum Camera_VSyncPolarity_ Camera_VSyncPolarity
Camera VSync polarity.
Camera Parameters.
Definition: Camera.h:399
Definition: Camera.h:371
Camera_IfSynchoronisation_
Camera interface synchronization.
Definition: Camera.h:359
Camera_ByteOrder byteOrder
Definition: Camera.h:416
Camera_ControlFxn controlFxn
Definition: Camera.h:481
Camera Global configuration.
Definition: Camera.h:504
Definition: Camera.h:349
void const * hwAttrs
Definition: Camera.h:512
Definition: Camera.h:323
Definition: Camera.h:333
Camera_CaptureMode captureMode
Definition: Camera.h:401
Camera_IfSynchoronisation interfaceSync
Definition: Camera.h:419
Copyright 2017, Texas Instruments Incorporated