/*   EXTRAITS DE LA LICENCE
	Copyright CEA, contributeurs : Luc BILLARD et Damien
	CALISTE, laboratoire L_Sim, (2001-2005)
  
	Adresse mèl :
	BILLARD, non joignable par mèl ;
	CALISTE, damien P caliste AT cea P fr.

	Ce logiciel est un programme informatique servant à visualiser des
	structures atomiques dans un rendu pseudo-3D. 

	Ce logiciel est régi par la licence CeCILL soumise au droit français et
	respectant les principes de diffusion des logiciels libres. Vous pouvez
	utiliser, modifier et/ou redistribuer ce programme sous les conditions
	de la licence CeCILL telle que diffusée par le CEA, le CNRS et l'INRIA 
	sur le site "http://www.cecill.info".

	Le fait que vous puissiez accéder à cet en-tête signifie que vous avez 
	pris connaissance de la licence CeCILL, et que vous en avez accepté les
	termes (cf. le fichier Documentation/licence.fr.txt fourni avec ce logiciel).
*/

/*   LICENCE SUM UP
	Copyright CEA, contributors : Luc BILLARD et Damien
	CALISTE, laboratoire L_Sim, (2001-2005)

	E-mail address:
	BILLARD, not reachable any more ;
	CALISTE, damien P caliste AT cea P fr.

	This software is a computer program whose purpose is to visualize atomic
	configurations in 3D.

	This software is governed by the CeCILL  license under French law and
	abiding by the rules of distribution of free software.  You can  use, 
	modify and/ or redistribute the software under the terms of the CeCILL
	license as circulated by CEA, CNRS and INRIA at the following URL
	"http://www.cecill.info". 

	The fact that you are presently reading this means that you have had
	knowledge of the CeCILL license and that you accept its terms. You can
	find a copy of this licence shipped with this software at Documentation/licence.en.txt.
*/
#ifndef TOOLSHADE_H
#define TOOLSHADE_H

#include <glib.h>

/**
 * Shade_struct
 *
 * Opaque structure to store linear shade informations.
 */
struct Shade_struct;
/**
 * Shade:
 *
 * Short name to address Shade_struct objects.
 */
typedef struct Shade_struct Shade;

/**
 * ShadeColorMode:
 * @shade_colorModeRGB: variation described in the shade are applied to RGB coding colors ;
 * @shade_colorModeHSV: variation described in the shade are applied to HSV coding colors ;
 * @shade_nb_colorMode: number of modes available.
 *
 * Defines color mode : Red-Green-Blue or Hue-Saturation-Value.
 */
typedef enum
  {
    shade_colorModeRGB,
    shade_colorModeHSV,
    shade_nb_colorMode
  } ShadeColorMode;

/**
 * shadeNew:
 * @labelUTF8: a UTF8 string that shortly named this new shade ;
 * @vectA: an array of three floating point values ;
 * @vectB: an array of three floating point values ;
 * @vectX: an array of three boolean values ;
 * @colorMode: an integer that describes the color code (see #Shade_colorMode enumeration).
 *
 * Shades are linear. Their profiles are given by an AX+B formula, dealing on three channels.
 * These channels are defined by the @colorMode parameter. All given values are copied when
 * the new shade is created.
 *
 * Returns: the newly created Shade.
 */
Shade* shadeNew(const gchar* labelUTF8, float vectA[3], float vectB[3],
	       gboolean vectX[3], ShadeColorMode colorMode);
/**
 * shadeGet_label:
 * @shade: a valid #Shade object.
 *
 * Get the name (in UTF8) of the shade.
 *
 * Returns: a string naming the shade.
 */
gchar* shadeGet_label(Shade *shade);
/**
 * shadeGet_colorMode:
 * @shade: a valid #Shade object.
 *
 * Get the color mode of the shade (RGB or HSV).
 *
 * Returns: the color mode.
 */
ShadeColorMode shadeGet_colorMode(Shade *shade);
/**
 * shadeGet_colorTransformation:
 * @shade: a valid #Shade object ;
 * @vectA: a pointer to a floating point values array to store vect in AX+B ;
 * @vectB: a pointer to a floating point values array to store vect in AX+B ;
 * @vectX: a pointer to a gboolean values array to store vect in AX+B.
 *
 * This methods can get the linear color transformation. The given arrays (vectA, vectB
 * and vectX) are read-only.
 *
 * Returns: TRUE if @vectA, @vectB and @vectX have been set correctly.
 */
gboolean shadeGet_colorTransformation(Shade *shade, float **vectA, float **vectB, gboolean **vectX);
/**
 * shadeSet_pathToImage:
 * @shade: a valid #Shade object ;
 * @path: a string.
 *
 * An image can be associated to the shade and its path is set with this method. If the path
 * is not an absolute path, the real path used is the concatenation of the directory
 * of pixmaps (cf. v_sim_pixmaps_dir in #visu_basic.h) and the given path.
 *
 * Returns: TRUE if the path has been changed.
 */
gboolean shadeSet_pathToImage(Shade *shade, const gchar* path);
/**
 * shadeGet_pathToImage:
 * @shade: a valid #Shade object.
 *
 * Get the path (always absolute) of an image describing the shade.
 *
 * Returns: a path (absolute) or NULL if not has been set.
 */
gchar* shadeGet_pathToImage(Shade *shade);
/**
 * shadeGet_valueTransformedInRGB:
 * @shade: a valid #Shade object ;
 * @rgba: an array of size [4] ;
 * @value: the value ranged in [0;1].
 *
 * Give a RGBA vector for the given value.
 */
void shadeGet_valueTransformedInRGB(Shade *shade, float rgba[4], float value);
/**
 * shadeDraw_legend:
 * @shade: a valid #Shade object ;
 * @widthVal: a floating point value ;
 * @heightVal: a floating point value ;
 * @minMax: the min & max value of the represented shaded color ;
 * @marks: an array of values bounded by @minMax ;
 * @nbMarks: the number of elements in the @marks array.
 *
 * This method calls OpenGL primitive to draw a coloured legend on the rendering
 * surface. If @widthVal is negative then the default value in pixel is used. If @widthVal
 * is smaller than 1., the width is taken as a percentage of the width of the rendering area.
 * Finaly, if @widthVal is larger than 1., the width of the legend in pixel is the given value.
 * If @marks is not NULL, some marks are set on the legend for the given values.
 */
void shadeDraw_legend(Shade *shade, float widthVal, float heightVal,
		      float minMax[2], float *marks, int nbMarks);



/**
 * toolShadeListGet:
 *
 * It returns a read-only pointer to the internal shade list. Use toolShadeListAppend()
 * to add new shades to this list.
 *
 * Returns: a pointer to the internal shade list.
 */
GList* toolShadeListGet();
/**
 * toolShadeListAppend:
 * @shade: a #Shade object.
 *
 * Add a shape to the internal list. Use the return value or toolShadeListGet() method
 * to look into this list.
 *
 * Returns: a read-only pointer to the internal shade list.
 */
GList* toolShadeListAppend(Shade *shade);
/**
 * toolShadeBuild_presetList:
 *
 * Create a list of preset shades.
 *
 * Returns: a read-only pointer to the internal shade list.
 */
GList* toolShadeBuild_presetList();


#endif