## renderingSpin

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

## Synopsis

    enum                SpinDrawingPolicy;
    enum                SpinModulusPolicy;
    enum                VisuSpinShapeId;
    enum                SpinFileType;
    #define             SPINVALUES_ID
    #define             SPINMAXMODULUS_ID
    #define             VISU_RENDERING_SPIN_NAME
    #define             VISU_RENDERING_SPIN_TYPE
    #define             VISU_RENDERING_SPIN                 (obj)
    #define             VISU_RENDERING_SPIN_CLASS           (klass)
    #define             IS_VISU_RENDERING_SPIN_TYPE         (obj)
    #define             IS_VISU_RENDERING_SPIN_CLASS        (klass)
    #define             VISU_RENDERING_SPIN_GET_CLASS       (obj)
    GType               visu_rendering_spin_get_type        (void);
                        VisuRenderingSpinPriv;
                        VisuRenderingSpinClass;
                        VisuRenderingSpin;
    VisuRenderingSpin*  visu_rendering_spin_new             ();
    const char*         visu_renderingSpin_getShapeNameI18n (VisuSpinShapeId n);
    SpinDrawingPolicy   visu_renderingSpin_getHidingPolicyFromName
                                                            (const char *name);
    const char*         visu_renderingSpin_getHidingPolicyName
                                                            (SpinDrawingPolicy n);
    const char*         visu_renderingSpin_getHidingPolicyNameI18n
                                                            (SpinDrawingPolicy n);
    enum                SpinElementResources;
    gpointer            rspin_getElementResource            (VisuElement *ele,
                                                             SpinElementResources property,
                                                             GType *type);
    gboolean            rspin_setElementResource_boolean    (VisuElement *ele,
                                                             SpinElementResources property,
                                                             gboolean value);
    gboolean            rspin_setElementResource_uint       (VisuElement *ele,
                                                             SpinElementResources property,
                                                             guint value);
    gboolean            rspin_setElementResource_float      (VisuElement *ele,
                                                             SpinElementResources property,
                                                             gfloat value);
    gboolean            rspin_getElementResource_boolean    (VisuElement *ele,
                                                             SpinElementResources property);
    guint               rspin_getElementResource_uint       (VisuElement *ele,
                                                             SpinElementResources property);
    gfloat              rspin_getElementResource_float      (VisuElement *ele,
                                                             SpinElementResources property);

## Object Hierarchy

      GObject
       +----VisuRendering
             +----VisuRenderingSpin

## Properties

      "cone-omega"               gfloat                : Read / Write
      "cone-phi"                 gfloat                : Read / Write
      "cone-theta"               gfloat                : Read / Write
      "hiding-mode"              guint                 : Read / Write
      "modulus-scaling"          guint                 : Read / Write
      "use-atomic"               gboolean              : Read / Write

## Signals

      "colorisationChange"                             : Run Last / No Recursion / No Hooks

## 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 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 the number of modes.

### enum SpinModulusPolicy

    typedef enum
      {
        policyNoneModulus,
        policyPerTypeModulus,
        policyGlobalModulus,
        policyNbModulusModes
      } SpinModulusPolicy;

Different policy to render the spin depending on the modulus.

`policyNoneModulus` | arrows have all the same size, whatever the modulus value.
`policyPerTypeModulus` | arrows are scaled per node type.
`policyGlobalModulus` | arrows are scaled globaly.
`policyNbModulusModes` | a flag to count the number of modes.

### enum VisuSpinShapeId

    typedef enum
      {
        VISU_RENDERING_SPIN_ARROW_SMOOTH,
        VISU_RENDERING_SPIN_ARROW_SHARP,
        VISU_RENDERING_SPIN_ELLIPSOID,
        VISU_RENDERING_SPIN_TORUS,
        /*< private >*/
        nbSpinShapes
      } VisuSpinShapeId;

An identifier for the different shapes to draw elements.

`VISU_RENDERING_SPIN_ARROW_SMOOTH` | the shape is smooth and rounded ;
`VISU_RENDERING_SPIN_ARROW_SHARP` | the shape is built on squares ;
`VISU_RENDERING_SPIN_ELLIPSOID` | the shape is an ellipsoid ;
`VISU_RENDERING_SPIN_TORUS` | the shape is a torus (direction of the arrow is normal to the torus plane).
`nbSpinShapes` | private.

### enum SpinFileType

    typedef enum
      {
        FILE_KIND_POSITION,
        FILE_KIND_SPIN
      } SpinFileType;

These are keys for the storing of spin files in a VisuData object.

`FILE_KIND_POSITION` | define a position file ;
`FILE_KIND_SPIN` | define a spin description file.

### SPINVALUES_ID

    #define SPINVALUES_ID     "spinRendering_values"

This flag should be used when creating a new spin rendering method as the flag for the spin values as node properties (see `visu_node_property_newPointer()`).

### SPINMAXMODULUS_ID

    #define SPINMAXMODULUS_ID "spinRendering_maxModulus"

This flag should be used when creating a new spin rendering method as the flag for the max modulus values as a VisuNode property (see `visu_node_property_newPointer()`).

### VISU_RENDERING_SPIN_NAME

    #define VISU_RENDERING_SPIN_NAME "Spin visualisation"

Public name of the spin rendering mode.

### VISU_RENDERING_SPIN_TYPE

    #define VISU_RENDERING_SPIN_TYPE	     (visu_rendering_spin_get_type ())

return the type of VisuRenderingSpin.

### VISU_RENDERING_SPIN()

    #define VISU_RENDERING_SPIN(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_RENDERING_SPIN_TYPE, VisuRenderingSpin))

Cast the given `obj` into VisuRenderingSpin type.

`obj` : | a GObject to cast.

### VISU_RENDERING_SPIN_CLASS()

    #define VISU_RENDERING_SPIN_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_RENDERING_SPIN_TYPE, VisuRenderingSpinClass))

Cast the given `klass` into VisuRenderingSpinClass.

`klass` : | a GObjectClass to cast.

### IS_VISU_RENDERING_SPIN_TYPE()

    #define IS_VISU_RENDERING_SPIN_TYPE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_RENDERING_SPIN_TYPE))

Test if the given `ogj` is of the type of VisuRenderingSpin object.

`obj` : | a GObject to test.

### IS_VISU_RENDERING_SPIN_CLASS()

    #define IS_VISU_RENDERING_SPIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_RENDERING_SPIN_TYPE))

Test if the given `klass` is of the type of VisuRenderingSpinClass class.

`klass` : | a GObjectClass to test.

### VISU_RENDERING_SPIN_GET_CLASS()

    #define VISU_RENDERING_SPIN_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_RENDERING_SPIN_TYPE, VisuRenderingSpinClass))

It returns the class of the given `obj`.

`obj` : | a GObject to get the class of.

### visu_rendering_spin_get_type ()

    GType               visu_rendering_spin_get_type        (void);

This method returns the type of VisuRenderingSpin, use VISU_RENDERING_SPIN_TYPE instead.

Returns : | the type of VisuRenderingSpin.

### VisuRenderingSpinPriv

    typedef struct _VisuRenderingSpinPriv VisuRenderingSpinPriv;

An opaque structure.

### VisuRenderingSpinClass

    typedef struct _VisuRenderingSpinClass VisuRenderingSpinClass;

An opaque structure.

### VisuRenderingSpin

    typedef struct _VisuRenderingSpin VisuRenderingSpin;

An opaque structure.

### visu_rendering_spin_new ()

    VisuRenderingSpin*  visu_rendering_spin_new             ();

Create the structure and initialise its values.

Returns : | a newly allocate VisuRenderingSpin object.

Since 3.6

### visu_renderingSpin_getShapeNameI18n ()

    const char*         visu_renderingSpin_getShapeNameI18n (VisuSpinShapeId n);

This routine returnes the translated name in UTF-8 corresponding to the given shape id.

`n` : | an id for spin shape.
Returns : | a string owned by V_Sim.. type utf8

### visu_renderingSpin_getHidingPolicyFromName ()

    SpinDrawingPolicy   visu_renderingSpin_getHidingPolicyFromName
                                                            (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.. type filename
Returns : | the maximum value if the name is invalid.

### visu_renderingSpin_getHidingPolicyName ()

    const char*         visu_renderingSpin_getHidingPolicyName
                                                            (SpinDrawingPolicy n);

Transform ids to untranslated names.

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

### visu_renderingSpin_getHidingPolicyNameI18n ()

    const char*         visu_renderingSpin_getHidingPolicyNameI18n
                                                            (SpinDrawingPolicy n);

Transform ids to translated names.

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

### 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.

### 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_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_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_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_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_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_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.

## Property Details

### The `"cone-omega"` property

      "cone-omega"               gfloat                : Read / Write

The omega angle to orientate the colourisation cone.

Allowed values: [0,360]

Default value: 0

### The `"cone-phi"` property

      "cone-phi"                 gfloat                : Read / Write

The phi angle to orientate the colourisation cone.

Allowed values: [0,360]

Default value: 0

### The `"cone-theta"` property

      "cone-theta"               gfloat                : Read / Write

The theta angle to orientate the colourisation cone.

Allowed values: [0,180]

Default value: 0

### The `"hiding-mode"` property

      "hiding-mode"              guint                 : Read / Write

The hiding policy for spin with a null modulus.

Allowed values: <= 3

Default value: 0

### The `"modulus-scaling"` property

      "modulus-scaling"          guint                 : Read / Write

The scaling policy based on modulus value.

Allowed values: <= 3

Default value: 0

### The `"use-atomic"` property

      "use-atomic"               gboolean              : Read / Write

If atomic rendering is used in addition to spin rendering.

Default value: FALSE

## Signal Details

### The `"colorisationChange"` signal

    void                user_function                      (VisuRenderingSpin *render,
                                                            gpointer           user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted whenever a change occur in the colourisation scheme of the spins.

`render` : | the object emitting the signal.
`user_data` : | user data set when the signal handler was connected.

Since 3.6