/*
 * targa.h
 *
 * Copyright (C) 2006 - 2009 by Joshua S. English.
 *
 * This software is the intellectual property of Joshua S. English. This
 * software is provided 'as-is', without any express or implied warranty. In no
 * event will the author be held liable for any damages arising from the use of
 * this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 * 1. The origin of this software must not be misrepresented; you must not
 *    claim that you wrote the original software. If you use this software in
 *    a product, an acknowledgment in the product documentation would be
 *    appreciated but is not required.
 *
 * 2. Altered source version must be plainly marked as such, and must not be
 *    misrepresented as being original software.
 *
 * 3. This notice may not be removed or altered from any source distribution.
 *
 *
 * Notes:
 *
 * A plugin to read targa (TGA) image files into an OpenGL-compatible RGBA
 * format, header file.
 *
 * Written by Joshua S. English.
 *
 *
 * The TARGA Specification:
 *
 *	Position:	Length:		Description:
 *	--------	------		-----------
 *	0			1			length of the image ID
 *	1			1			type of color map included (if any)
 *								0	=>	no color map
 *								1	=>	has color map
 *	2			1			image type
 *								0	=>	no image data
 *								1	=>	color-mapped image
 *								2	=>	true-color image
 *								3	=>	black & white image
 *								9	=>	RLE color-mapped image
 *								10	=>	RLE true-color image
 *								11	=>	RLE black & white image
 *	3			2			index of the first color-map entry as an offest
 *							into the color-map table
 *	5			2			color-map length (number of entries)
 *	7			1			color-map entry length - (number of bits per entry)
 *	8			2			x-origin of image
 *	10			2			y-origin of image
 *	12			2			image width in pixels
 *	14			2			image height in pixels
 *	16			1			pixel depth - the number of bits per pixel
 *	17			1			image descriptor
 *	n			var			image id - only exists if non-zero
 *	n			var			color-map data - only exists if non-zero
 *	n			var			image data
 */

#if !defined(_TARGA_H)

#define _TARGA_H


// define targa public constants

#define TARGA_COLOR_RED										1
#define TARGA_COLOR_GREEN									2
#define TARGA_COLOR_BLUE									3
#define TARGA_COLOR_ALPHA									4

// define targa public data types

typedef struct _Targa {
	int width;
	int height;
	int imageLength;
	unsigned char *image;
} Targa;

#ifdef __cplusplus
extern "C" {
#endif

// declare targa public functions

/**
 * targa_init()
 *
 * Initilize the Targa structure for utilization.
 *
 * @param	targa(in)	The Targa struct to initialize.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_init(Targa *targa);


/**
 * targa_free()
 *
 * Free the Targa structure.
 *
 * @param	targa(in)	The Targa struct to free.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_free(Targa *targa);


/**
 * targa_getDimensions()
 *
 * Obtain the width and height in pixels of a loaded Targa image.
 *
 * @param	targa(in)	The Targa struct of a loaded image.
 *
 * @param	width(out)	The width in pixels of a loaded Targa image.
 *
 * @param	height(out)	The height in pixels of a loaded Targa image.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_getDimensions(Targa *targa, int *width, int *height);


/**
 * targa_getImageLength()
 *
 * Obtain the length in bytes of the serialized RGBA image.
 *
 * @param	targa(in)			The Targa struct of a loaded image.
 *
 * @param	imageLength(out)	The length in bytes of the RGBA image.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_getImageLength(Targa *targa, int *imageLength);


/**
 * targa_getRgbaTexture()
 *
 * Obtain the serialized RGBA texture and its' length from a Targa image.
 *
 * @param	targa(in)			The Targa struct of a loaded image.
 *
 * @param	texture(out)		The serialized RGBA image pointer.
 *
 * @param	textureLength(out)	The serialized RGBA image length in bytes.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_getRgbaTexture(Targa *targa, char **texture, int *textureLength);


/**
 * targa_loadFromFile()
 *
 * Load a targa file and decode it into a 32-bit RGBA serialized image.
 *
 * @param	targa(in)		The Targa struct of an image to load.
 *
 * @param	filename(in)	The filename of the image to load.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_loadFromFile(Targa *targa, char *filename);


/**
 * targa_loadFromData()
 *
 * Load the targa from an in-memory location and decode it into a 32-bit RGBA
 * serialize image.
 *
 * @param	targa(in)		The Targa struct an image to load.
 *
 * @param	data(in)		A pointer to an in-memory location containing a
 *							Targa image.
 *
 * @param	dataLength(in)	The length of the Targa in-memory image.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_loadFromData(Targa *targa, const unsigned char *data, int dataLength);


/**
 * targa_applyRgbaMask()
 *
 * Apply a red, green, blue or alpha-channel additive color-mask to a loaded
 * Targa image.
 *
 * @param	targa(in)		The Targa struct of a loaded image.
 *
 * @param	colorType(in)	The color channel to mask.
 *
 * @param	value(in)		The color code (0 - 255) to mask.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_applyRgbaMask(Targa *targa, int colorType, unsigned char value);


/**
 * targa_setRgbaChannel()
 *
 * Apply a red, green, blue or alpha-channel additive color-channel
 * replacement to a loaded Targa image.
 *
 * @param	targa(in)		The Targa struct of a loaded image.
 *
 * @param	colorType(in)	The color channel to replace.
 *
 * @param	value(in)		The color code (0 - 255) to replace.
 *
 * @return	An integer where zero is pass, less than zero is failure.
 */
int targa_setRgbaChannel(Targa *targa, int colorType, unsigned char value);

#ifdef __cplusplus
} // extern "C"
#endif

#endif // _TARGA_H