## renderingSpin

renderingSpin — A module able to represent atoms by their position and spin.

## Synopsis

    enum        SpinGlobalResources;
    enum        SpinElementResources;
    enum        SpinDrawingPolicy;

    void        rspin_addLoadMethod             (RenderingFormatLoad *meth);
    gboolean    rspin_load                      (VisuData *data,
                                                 FileFormat *format,
                                                 GError **error);
    gboolean    rspin_setGlobalResource_boolean (SpinGlobalResources property,
                                                 gboolean value);
    gboolean    rspin_getGlobalResource_boolean (SpinGlobalResources property);
    gboolean    rspin_setGlobalResource_float   (SpinGlobalResources property,
                                                 gfloat value);
    gfloat      rspin_getGlobalResource_float   (SpinGlobalResources property);
    gboolean    rspin_setGlobalResource_uint    (SpinGlobalResources property,
                                                 guint value);
    guint       rspin_getGlobalResource_uint    (SpinGlobalResources property);
    gpointer    rspin_getGlobalResource         (SpinGlobalResources property,
                                                 GType *type);
    guint       rspin_getElementResource_uint   (VisuElement *ele,
                                                 SpinElementResources property);
    gboolean    rspin_setElementResource_uint   (VisuElement *ele,
                                                 SpinElementResources property,
                                                 guint value);
    gfloat      rspin_getElementResource_float  (VisuElement *ele,
                                                 SpinElementResources property);
    gboolean    rspin_setElementResource_float  (VisuElement *ele,
                                                 SpinElementResources property,
                                                 gfloat value);
    gboolean    rspin_setElementResource_boolean
                                                (VisuElement *ele,
                                                 SpinElementResources property,
                                                 gboolean value);
    gboolean    rspin_getElementResource_boolean
                                                (VisuElement *ele,
                                                 SpinElementResources property);
    gpointer    rspin_getElementResource        (VisuElement *ele,
                                                 SpinElementResources property,
                                                 GType *type);
    int         rspin_get_number_of_shapes      ();
    int         rspin_shape_name_to_number      (const char *name);
    const char* rspin_shape_number_to_name      (int n);
    const char* rspin_shape_number_to_translated_name
                                                (int n);
    const char* rspin_hiding_number_to_name     (int n);
    const char* rspin_hiding_number_to_translated_name
                                                (int n);
    int         rspin_hiding_name_to_number     (const char *name);

    RenderingMethod* initSpin                   ();

## Description

This method draws arrows to represent atoms. Each arrow has a given orientation which is set acording to parameters. This is one way to represent the spin of an atom. These arrows direction are determined by the spin of each atom. It is designed to read two separate files : one containing the position of the atoms, the other containing the spin of each atom. Of course these two files need to have the exact same number of atoms and also need to sort atoms in the same order.

## Details

### enum SpinGlobalResources

    typedef enum
      {
        spin_globalConeTheta,
        spin_globalConePhi,
        spin_globalColorWheel,
        spin_globalHidingMode,
        spin_globalAtomic,
        spin_globalModulus,
        spin_nbGlobalResources
      } SpinGlobalResources;

These are resources that impact the entire rendering spin method. They can be accessed through `rspin_getGlobalResource()` or `rspin_setGlobalResource_boolean()` and other similar methods.

`spin_globalConeTheta` | the theta angle to set the color cone ;
`spin_globalConePhi` | the phi angle to set the color cone ;
`spin_globalColorWheel` | an angle to set the color origin around the z axis of the cone ;
`spin_globalHidingMode` | an id used to define the policy used to draw spin with null modulus (see SpinDrawingPolicy) ;
`spin_globalAtomic` | if TRUE, atoms are drawn with spins ;
`spin_globalModulus` | if TRUE the total length is proportional to the modulus ;
`spin_nbGlobalResources` | number of global resources.

### enum SpinElementResources

    typedef enum
      {
        spin_elementHatLength,
        spin_elementTailLength,
        spin_elementHatRadius,
        spin_elementTailRadius,
        spin_elementHatColor,
        spin_elementTailColor,
        spin_elementAAxis,
        spin_elementBAxis,
        spin_elementElipsoidColor,
        spin_elementShape,
        spin_nbElementResources
      } SpinElementResources;

These are resources defined for each element. They can be accessed with `rspin_getElementResource()` or `rspin_getElementResource_boolean()` and other methods of the same kind.

`spin_elementHatLength` | the length of the pointing element ;
`spin_elementTailLength` | the length of the tail ;
`spin_elementHatRadius` | the raidus of the pointing element ;
`spin_elementTailRadius` | the radius of the tail ;
`spin_elementHatColor` | if TRUE, the pointing part use the color of the element ;
`spin_elementTailColor` | if TRUE, the tail uses the color of the element ;
`spin_elementAAxis` | the size of the A axis (elipsoid shape) ;
`spin_elementBAxis` | the size of the B axis (elipsoid shape) ;
`spin_elementElipsoidColor` | if TRUE, the elipsoid uses the color of the element ;
`spin_elementShape` | an id to defined the shape (rounded arrow, elipsoid...) ;
`spin_nbElementResources` | number of resources per element.

### enum SpinDrawingPolicy

    typedef enum
      {
        policyAlwaysSpin,
        policyHideNullSpin,
        policyAtomicNullSpin,
        policyNbModes
      } SpinDrawingPolicy;

Different policy to render the spin when the modulus is null. This policy is applied for all VisuElement.

`policyAlwaysSpin` | Arrows are drawn whatever the modulus value.
`policyHideNullSpin` | Spin with a null modulus are hidden.
`policyAtomicNullSpin` | Follow atomic rendering for null modulus.
`policyNbModes` | a flag to count number of elements.

### rspin_addLoadMethod ()

    void        rspin_addLoadMethod             (RenderingFormatLoad *meth);

This routine is used to register a new load method with its description (file formats, name...). The list of all known load methods is automatically resorted after a call to this method to reflect the priorities.

`meth` : | a new load method.

### rspin_load ()

    gboolean    rspin_load                      (VisuData *data,
                                                 FileFormat *format,
                                                 GError **error);

Try to load the spin file declared in the `data`. It tries all formats added with `rspin_addLoadMethod()`.

`data` : | a VisuData object ;
`format` : | a pointer on a format (can be NULL if format is to be guessed) ;
`error` : | a pointer to store a possible error.
Returns : | FALSE if the file can't be loaded.

### rspin_setGlobalResource_boolean ()

    gboolean    rspin_setGlobalResource_boolean (SpinGlobalResources property,
                                                 gboolean value);

This method is used to change global resources that are boolean.

`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_getGlobalResource_boolean ()

    gboolean    rspin_getGlobalResource_boolean (SpinGlobalResources property);

This is the specific method to retrieve value of boolean global resources.

`property` : | the id of the property to get.
Returns : | the boolean value.

### rspin_setGlobalResource_float ()

    gboolean    rspin_setGlobalResource_float   (SpinGlobalResources property,
                                                 gfloat value);

This method is used to change global resources that are floating point.

`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_getGlobalResource_float ()

    gfloat      rspin_getGlobalResource_float   (SpinGlobalResources property);

This is the specific method to retrieve value of floating point global resources.

`property` : | the id of the property to get.
Returns : | the floating point value.

### rspin_setGlobalResource_uint ()

    gboolean    rspin_setGlobalResource_uint    (SpinGlobalResources property,
                                                 guint value);

This method is used to change global resources that are unsigned int.

`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_getGlobalResource_uint ()

    guint       rspin_getGlobalResource_uint    (SpinGlobalResources property);

This is the specific method to retrieve value of unsigned int global resources.

`property` : | the id of the property to get.
Returns : | the unsigned int value.

### rspin_getGlobalResource ()

    gpointer    rspin_getGlobalResource         (SpinGlobalResources property,
                                                 GType *type);

This is a generic method to access global resources. Use `rspin_setGlobalResource_boolean()` is favored if the type of the value is known. If the returned value is not NULL the argument `type` contains the type of the returned value.

`property` : | the name of the resource ;
`type` : | a location to store the type.
Returns : | a pointer to the location where the value for the given global resource is stored.

### rspin_getElementResource_uint ()

    guint       rspin_getElementResource_uint   (VisuElement *ele,
                                                 SpinElementResources property);

This is the specific method to retrieve value of unsigned int element resources.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to get.
Returns : | the unsigned int value.

### rspin_setElementResource_uint ()

    gboolean    rspin_setElementResource_uint   (VisuElement *ele,
                                                 SpinElementResources property,
                                                 guint value);

This method is used to change element resources that are unsigned int.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_getElementResource_float ()

    gfloat      rspin_getElementResource_float  (VisuElement *ele,
                                                 SpinElementResources property);

This is the specific method to retrieve value of floating point element resources.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to get.
Returns : | the floating point value.

### rspin_setElementResource_float ()

    gboolean    rspin_setElementResource_float  (VisuElement *ele,
                                                 SpinElementResources property,
                                                 gfloat value);

This method is used to change element resources that are floating point.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_setElementResource_boolean ()

    gboolean    rspin_setElementResource_boolean
                                                (VisuElement *ele,
                                                 SpinElementResources property,
                                                 gboolean value);

This method is used to change element resources that are boolean.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to set ;
`value` : | its value.
Returns : | TRUE if the value was changed.

### rspin_getElementResource_boolean ()

    gboolean    rspin_getElementResource_boolean
                                                (VisuElement *ele,
                                                 SpinElementResources property);

This is the specific method to retrieve value of boolean element resources.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the property to get.
Returns : | the boolean value.

### rspin_getElementResource ()

    gpointer    rspin_getElementResource        (VisuElement *ele,
                                                 SpinElementResources property,
                                                 GType *type);

This is a generic method to access resources per element. Use `rspin_setElementResource_boolean()` is favored if the type of the value is known (boolean in this exemple). If the returned value is not NULL the argument `type` contains the type of the returned value.

`ele` : | a pointer to a VisuElement object ;
`property` : | the id of the resource (see SpinElementResources) ;
`type` : | a location to store the type.
Returns : | a pointer to the location where the value for the given global resource is stored.

### rspin_get_number_of_shapes ()

    int         rspin_get_number_of_shapes      ();

Pouet

Returns : | the number of different shapes that can be used to draw spins

### rspin_shape_name_to_number ()

    int         rspin_shape_name_to_number      (const char *name);

`name` : | the name of the shape
Returns : | the number of the shape named `name`

### rspin_shape_number_to_name ()

    const char* rspin_shape_number_to_name      (int n);

`n` : | the number of the shape you want the name
Returns : | the name of the shape number `n`

### rspin_shape_number_to_translated_name ()

    const char* rspin_shape_number_to_translated_name
                                                (int n);

`n` : | the number of the shape you want the name
Returns : | the name of the shape number `n` translated and in UTF8.

### rspin_hiding_number_to_name ()

    const char* rspin_hiding_number_to_name     (int n);

Transform ids to untranslated names.

`n` : | an id for hiding policy.
Returns : | the name associated to the id.

### rspin_hiding_number_to_translated_name ()

    const char* rspin_hiding_number_to_translated_name
                                                (int n);

Transform ids to translated names.

`n` : | an id for hiding policy.
Returns : | the name associated to the id in UTF-8.

### rspin_hiding_name_to_number ()

    int         rspin_hiding_name_to_number     (const char *name);

In the config file, the hiding policy resource is stored with its name (untranslated). This method is used to retrieve the id from the name.

`name` : | a string.
Returns : | -1 if the name is invalid.

### initSpin ()

    RenderingMethod* initSpin                   ();

Create the whole method and initialise its values.

Returns : | a `RenderingMethod` pointer to the new method created. Used by the core to register it.