/*   EXTRAITS DE LA LICENCE
	Copyright CEA, contributeurs : Luc BILLARD et Damien
	CALISTE, laboratoire L_Sim, (2001-2006)
  
	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-2006)

	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);



/**
 * 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);



#endif
