/**
* @file			image_header.h
* @brief		Image header definition
* @author		Patrick Brunner - brunner@stettbacher.ch
* @author		Patrick Roth - roth@stettbacher.ch
* @version		1.1
* @date			2016-03-01
* @copyright	2012-2016 Stettbacher Signal Processing AG
* 
* @remarks
*
* <PRE>
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
* </PRE>
*
*/


#ifndef _IMAGE_HEADER_H
#define _IMAGE_HEADER_H

#include "o3000_portable.h"

#define O3000_IMG_HEADER_VERSION			4		///< O-3000 image header version

/**
 * Image header size in bytes
 * 
 * @note The struct img_header_t defined below must be a multiple of 512 bytes.
 * The macro @ref IMAGE_HEADER_SIZE just helps to verify the header size, as done with
 * the assert command in image_header_init. Unfortunately, assertions in C can only
 * be performed at runtime, not at compile-time...
 */
#define IMAGE_HEADER_SIZE	512

/**
 * Image data format.
 * These are all possible values for the field format in struct img_header_t.
 */
enum enumDataFormat_t {
	DF_RAW_MONO_8 = 0,		///< monochrome image with 8 bit per pixel
	DF_RAW_MONO_12,			///< monochrome image with 12 bit per pixel
	DF_RAW_BAYER_8,			///< bayer image with 8 bit per pixel
	DF_RAW_BAYER_12,		///< bayer image with 12 bit per pixel
	DF_HDR_MONO_20_COMP,	///< 20 bit HDR monochrome image compressed to 12 bits
	DF_HDR_BAYER_20_COMP,	///< 20 bit HDR bayer image compressed to 12 bits
};

/**
 * Bayer pattern color order.
 * These are all possible values for the field bayer pattern in struct img_header_t.
 * The individual values describe the order of the pixels in the image data array.
 * Depending on the start coordinate, the pattern starts with a red, 
 * green (2 possibilities), or blue pixel.
 * The pattern then repeats every 2 pixels in the X- and Y-direction.
 * 
 * @code
 *  X   |	Y   | 1st row      | 2nd row      | enum value
 * -----+-------+--------------+--------------+-----------
 * even | even	| Gr, R, Gr, R | B, Gb, B, Gb | BP_GR
 *  odd | even	| R, Gr, R, Gr | Gb, B, Gb, B | BP_RG
 * even |  odd	| B, Gb, B, Gb | Gr, R, Gr, R | BP_BG
 *  odd |  odd	| Gb, B, Gb, B | R, Gr, R, Gr | BP_GB
 * 1st row: first row data within the region of interest
 * 
 * R:  red pixel
 * Gr: green pixel, adjacent to red pixel
 * Gb: green pixel, adjacent to blue pixel
 * B:  blue pixel
 * @endcode
 */
enum enumBayerPattern_t {
	BP_GR = 0,		///< first row: green-red-green-red-...
	BP_RG,			///< first row: red-green-red-green-...
	BP_BG,			///< first row: blue-green-blue-green-...
	BP_GB,			///< first row: green-blue-green-blue-...
};


/**
 * Image header (must be a multiple of 512 bytes)
 * 
 * @code
 * 
 * X/Y coordinate system
 * 
 *   +---------------------------------> x-axis
 *   |0/0		1/0		2/0
 *   |0/1		1/1		2/1
 *   |
 *   |        +-----------------+
 *   |        |                 |        
 *   |        |  field of view  |
 *   |        |                 |
 *   |        +-----------------+
 *   v
 * y-axis
 * 
 * @endcode
 * 
 * - upper left corner starts with coordinate 0/0
 * - the image width defines the maximum horizontal view in x-direction
 * - the image height defines the maximum vertical view y-direction
 * 
 * As the sensor data may contain embedded statistics which should be ignored
 * by the application, image_start defines the offset in bytes of the actual image
 * data.  The payload size contains the regular image size plus the size 
 * of the embedded data. If there is no embedded data, image start offset 
 * is 0 and the payload and image size are equal.
 * 
 * @note Embedded data not only contains statistics lines at the beginning, 
 * but also at the end of the image. The field @ref bayer_pattern is defined for bayer-based
 * data formats only (e.g. DF_RAW_BAYER_8).
 */
struct img_header_t {
	
	// since image header version 1
	uint32_t	preamble[2]; 	///< constant preamble 											(8 bytes)
	uint32_t	version;		///< header version number 										(4 bytes)
	uint32_t	payload_size;	///< payload size (in bytes)									(4 bytes)
	uint32_t	image_start;	///< image start offset (in bytes)										(4 bytes)
	uint32_t	image_size;		///< image size (in bytes) 										(4 bytes)
	uint32_t	width;			///< current image width (x-direction) (in pixels) 				(4 bytes)
	uint32_t	height;			///< current image height (y-direction) (in pixels) 			(4 bytes)
	uint32_t	format;			///< image data format (see @ref enumDataFormat_t)				(4 bytes)
	uint32_t	frame_count;	///< frame sequence number 										(4 bytes)
	
	// since image header version 2
	uint32_t	bayer_pattern;	///< bayer pattern color order (see @ref enumBayerPattern_t)	(4 bytes)
	
	// since image header version 3
	uint32_t	datarate;		///< USB data rate in bytes per seconds							(4 bytes)
	float		fps;			///< frames per seconds											(4 bytes)
	
	// since image header version 4
	uint16_t	fov_x_start;	///< start x-cooredinate of current field of view				(2 bytes)
	uint16_t	fov_x_end;		///< end x-cooredinate of current field of view					(2 bytes)
	uint16_t	fov_y_start;	///< start y-cooredinate of current field of view				(2 bytes)
	uint16_t	fov_y_end;		///< end y-cooredinate of current field of view					(2 bytes)
	
	uint8_t		padding[452];	///< padding bytes to fill header								(452 bytes)
} __packed__;


#endif // _IMAGE_HEADER_H