Description: The GLE Tubing and Extrusion Library is a graphics programming interface (API) for drawing tubing, extrusions and sweeps using the OpenGL API.
Keywords: GLE, tubing, extrusion, graphics, OpenGL, lathe, sweep, torus, polycylinder, polycone, contour, parallel translation, helix, texture mapping

# Subroutine Documentation

## Some Types

    typedef double gleDouble;
    typedef gleDouble gleAffine[2][3];

## Subroutine Descriptions

     void glePolyCylinder (int npoints,		/* num points in polyline */
                       gleDouble point_array[][3],	/* polyline vertces */
                       float color_array[][3],	/* colors at polyline verts */
                       gleDouble radius);		/* radius of polycylinder */

     void glePolyCylinder_c4f (int npoints,		/* num points in polyline */
                       gleDouble point_array[][3],	/* polyline vertces */
                       float color_array[][4],	/* colors at polyline verts */
                       gleDouble radius);		/* radius of polycylinder */

  Draw polycylinder, specified as a polyline.

  Note that neither the very first segment, nor the very last segment are drawn. The first and last segments serve only to define the angle of the join at the very ends of the polyline. Thus, to draw one segment, three must be specified. To draw two segments, four must be specified, etc.

  The color array may be NULL. If NULL, the current color is used. If not NULL, the glColor3f() routine is used to set the color; therefore, specifying the glColorMaterial() subroutine before this primitive can be used to set diffuse, specular, ambient, etc. colors. The glePolyCylinder_c4f() routine calls glColor4f() instead, thus allowing alpha-blending (transparency) to be performed.

  By default, the cross-section of the cylinder is drawn as a 20-sided polygon. This number can be changed using the gleSetNumSides() routine.

     void glePolyCone (int npoints,	 /* numpoints in poly-line */
                       gleDouble point_array[][3],	/* polyline vertices */
                       float color_array[][3],	/* colors at polyline verts */
                       gleDouble radius_array[]); /* cone radii at polyline verts */

     void glePolyCone_c4f (int npoints,	 /* numpoints in poly-line */
                       gleDouble point_array[][3],	/* polyline vertices */
                       float color_array[][4],	/* colors at polyline verts */
                       gleDouble radius_array[]); /* cone radii at polyline verts */

  Draw polycone, specified as a polyline with radii.

  Note that neither the very first segment, nor the very last segment are drawn. The first and last segments serve only to define the angle of the join at the very ends of the polyline. Thus, to draw one segment, three must be specified. To draw two segments, four must be specified, etc.

  The color array may be NULL. If NULL, the current color is used. If not NULL, the glColor3f() routine is used to set the color; therefore, specifying the glColorMaterial() subroutine before this primitive can be used to set diffuse, specular, ambient, etc. colors. The glePolyCone_c4f() routine calls glColor4f() instead, thus allowing alpha-blending (transparency) to be performed.

  By default, the cross-section of the cylinder is drawn as a 20-sided polygon. This number can be changed using the gleSetNumSides() routine.

     int gleGetNumSides(void);
     void gleSetNumSides(int slices);

  Query and set the GLE cylinder and cone roundness. When GLE draws a cylinder or a cone, it approximates the circular cross-section with a polygon (of 20 sides by default). These subroutines can be used to change the default number of sides in this cross-section. A smaller number of sides can typically be drawn much faster, at the loss of some visual accuracy. Increasing the number of sides to more than 20 will typically have no noticeable visual effect.

     void gleExtrusion (int ncp,         /* number of contour points */
                    gleDouble contour[][2],     /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],            /* up vector for contour */
                    int npoints,            /* numpoints in poly-line */
                    gleDouble point_array[][3], /* polyline vertices */
                    float color_array[][3]); /* colors at polyline verts */

     void gleExtrusion_c4f (int ncp,         /* number of contour points */
                    gleDouble contour[][2],     /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],            /* up vector for contour */
                    int npoints,            /* numpoints in poly-line */
                    gleDouble point_array[][3], /* polyline vertices */
                    float color_array[][4]); /* colors at polyline verts */

  Extrude arbitrary 2D contour along arbitrary 3D path. The argument "contour" specifies the 2D contour to be extruded, while the argument "point_array" specifies the path along which to extrude. The vector "up" defines the orientation of the contour y-axis in real 3D space.

  Note that neither the very first segment, nor the very last segment are drawn. The first and last segments serve only to define the angle of the join at the very ends of the polyline. Thus, to draw one segment, three must be specified. To draw two segments, four must be specified, etc.

  The normal array may be NULL. If it is, normal vectors will NOT be automatically generated, and the object will look terrible when lit.

  The color array may be NULL. If NULL, the current color is used. If not NULL, the glColor3f() routine is used to set the color; therefore, specifying the glColorMaterial() subroutine before this primitive can be used to set diffuse, specular, ambient, etc. colors. The gleExtrusion_c4f() routine calls glColor4f() instead, thus allowing alpha-blending (transparency) to be performed.

     void gleTwistExtrusion (int ncp,         /* number of contour points */
                    gleDouble contour[][2],    /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],           /* up vector for contour */
                    int npoints,           /* numpoints in poly-line */
                    gleDouble point_array[][3],        /* polyline vertices */
                    float color_array[][3],        /* color at polyline verts */
                    gleDouble twist_array[]);   /* contour twists (in degrees) */

     void gleTwistExtrusion_c4f (int ncp,         /* number of contour points */
                    gleDouble contour[][2],    /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],           /* up vector for contour */
                    int npoints,           /* numpoints in poly-line */
                    gleDouble point_array[][3],        /* polyline vertices */
                    float color_array[][4],        /* color at polyline verts */
                    gleDouble twist_array[]);   /* contour twists (in degrees) */

  Extrude arbitrary 2D contour along arbitrary 3D path, specifying local rotations (twists). As the contour is extruded, it will be twisted by the amount specified in the array "twist_array". The angles are measured in degrees, and the rotation is about the origin of the contour coordinate system.

  The argument "contour" specifies the 2D contour to be extruded, while the argument "point_array" specifies the path along which to extrude. The vector "up" defines the orientation of the contour y-axis in real 3D space.

  Note that neither the very first segment, nor the very last segment are drawn. The first and last segments serve only to define the angle of the join at the very ends of the polyline. Thus, to draw one segment, three must be specified. To draw two segments, four must be specified, etc.

  The normal array may be NULL. If it is, normal vectors will NOT be automatically generated, and the object will look terrible when lit.

  The color array may be NULL. If NULL, the current color is used. If not NULL, the glColor3f() routine is used to set the color; therefore, specifying the glColorMaterial() subroutine before this primitive can be used to set diffuse, specular, ambient, etc. colors. The gleTwistExtrusion_c4f() routine calls glColor4f() instead, thus allowing alpha-blending (transparency) to be performed.

     void gleSuperExtrusion (int ncp,  /* number of contour points */
                    gleDouble contour[][2],    /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],           /* up vector for contour */
                    int npoints,           /* numpoints in poly-line */
                    gleDouble point_array[][3],        /* polyline vertices */
                    float color_array[][3],        /* color at polyline verts */
                    gleDouble xform_array[][2][3]);   /* 2D contour xforms */

     void gleSuperExtrusion_c4f (int ncp,  /* number of contour points */
                    gleDouble contour[][2],    /* 2D contour */
                    gleDouble cont_normal[][2], /* 2D contour normals */
                    gleDouble up[3],           /* up vector for contour */
                    int npoints,           /* numpoints in poly-line */
                    gleDouble point_array[][3],        /* polyline vertices */
                    float color_array[][4],        /* color at polyline verts */
                    gleDouble xform_array[][2][3]);   /* 2D contour xforms */

  Extrude arbitrary 2D contour along arbitrary 3D path, specifying local affine transformations. As the contour is extruded, the affine will be applied to the points in the contour.

  The argument "contour" specifies the 2D contour to be extruded, while the argument "point_array" specifies the path along which to extrude. The vector "up" defines the orientation of the contour y-axis in real 3D space.

  Note that neither the very first segment, nor the very last segment are drawn. The first and last segments serve only to define the angle of the join at the very ends of the polyline. Thus, to draw one segment, three must be specified. To draw two segments, four must be specified, etc.

  The normal array may be NULL. If it is, normal vectors will NOT be automatically generated, and the object will look terrible when lit.

  The color array may be NULL. If NULL, the current color is used. If not NULL, the glColor3f() routine is used to set the color; therefore, specifying the glColorMaterial() subroutine before this primitive can be used to set diffuse, specular, ambient, etc. colors. The gleSuperExtrusion_c4f() routine calls glColor4f() instead, thus allowing alpha-blending (transparency) to be performed.

     void gleSpiral (int ncp,        /* number of contour points */
                 gleDouble contour[][2],    /* 2D contour */
                 gleDouble cont_normal[][2], /* 2D contour normals */
                 gleDouble up[3],           /* up vector for contour */
                 gleDouble startRadius,	/* spiral starts in x-y plane */
                 gleDouble drdTheta,        /* change in radius per revolution */
                 gleDouble startZ,		/* starting z value */
                 gleDouble dzdTheta,        /* change in Z per revolution */
                 gleDouble startXform[2][3], /* starting contour affine xform */
                 gleDouble dXformdTheta[2][3], /* tangent change xform per revoln */
                 gleDouble startTheta,	/* start angle in x-y plane */
                 gleDouble sweepTheta);	/* degrees to spiral around */

  Sweep an arbitrary contour along a helical path.

  The axis of the helix lies along the modeling coordinate z-axis.

  An affine transform can be applied as the contour is swept. For most ordinary usage, the affines should be given as NULL.

  The "startXform[][]" is an affine matrix applied to the contour to deform the contour. Thus, "startXform" of the form

      |  cos     sin    0   |
      |  -sin    cos    0   |

  will rotate the contour (in the plane of the contour), while

      |  1    0    tx   |
      |  0    1    ty   |

  will translate the contour, and

      |  sx    0    0   |
      |  0    sy    0   |

  scales along the two axes of the contour. In particular, note that

      |  1    0    0   |
      |  0    1    0   |

  is the identity matrix.

  The "dXformdTheta[][]" is a differential affine matrix that is integrated while the contour is extruded. Note that this affine matrix lives in the tangent space, and so it should have the form of a generator. Thus, dx/dt's of the form

      |  0     r    0   |
      |  -r    0    0   |

  rotate the the contour as it is extruded (r == 0 implies no rotation, r == 2*PI implies that the contour is rotated once, etc.), while

      |  0    0    tx   |
      |  0    0    ty   |

  translates the contour, and

      |  sx    0    0   |
      |  0    sy    0   |

  scales it. In particular, note that

      |  0    0    0   |
      |  0    0    0   |

  is the identity matrix -- i.e. the derivatives are zero, and therefore the integral is a constant.

     void gleLathe (int ncp,        /* number of contour points */
                 gleDouble contour[][2],    /* 2D contour */
                 gleDouble cont_normal[][2], /* 2D contour normals */
                 gleDouble up[3],           /* up vector for contour */
                 gleDouble startRadius,	/* spiral starts in x-y plane */
                 gleDouble drdTheta,        /* change in radius per revolution */
                 gleDouble startZ,		/* starting z value */
                 gleDouble dzdTheta,        /* change in Z per revolution */
                 gleDouble startXform[2][3], /* starting contour affine xform */
                 gleDouble dXformdTheta[2][3], /* tangent change xform per revoln */
                 gleDouble startTheta,	/* start angle in x-y plane */
                 gleDouble sweepTheta);	/* degrees to spiral around */

  Sweep an arbitrary contour along a helical path. The sweep will be performed as a shear along the z-axis, so that the orientation of the contour is displaced, rather than translated, as the contour is swept.

  The axis of the helix lies along the modeling coordinate z-axis.

  An affine transform can be applied as the contour is swept. For most ordinary usage, the affines should be given as NULL.

     void gleHelicoid (gleDouble rToroid, /* circle contour (torus) radius */
                 gleDouble startRadius,	/* spiral starts in x-y plane */
                 gleDouble drdTheta,        /* change in radius per revolution */
                 gleDouble startZ,		/* starting z value */
                 gleDouble dzdTheta,        /* change in Z per revolution */
                 gleDouble startXform[2][3], /* starting contour affine xform */
                 gleDouble dXformdTheta[2][3], /* tangent change xform per revoln */
                 gleDouble startTheta,	/* start angle in x-y plane */
                 gleDouble sweepTheta);	/* degrees to spiral around */

  Generalized Torus. Similar to gleSpiral, except contour is a circle. Uses gleSpiral to draw.

     void gleToroid (gleDouble rToroid, /* circle contour (torus) radius */
                 gleDouble startRadius,	/* spiral starts in x-y plane */
                 gleDouble drdTheta,        /* change in radius per revolution */
                 gleDouble startZ,		/* starting z value */
                 gleDouble dzdTheta,        /* change in Z per revolution */
                 gleDouble startXform[2][3], /* starting contour affine xform */
                 gleDouble dXformdTheta[2][3], /* tangent change xform per revoln */
                 gleDouble startTheta,	/* start angle in x-y plane */
                 gleDouble sweepTheta);	/* degrees to spiral around */

  Generalized Torus. Similar to gleLathe, except contour is a circle. Uses gleLathe to draw.

     void gleScrew (int ncp,          /* number of contour points */
                 gleDouble contour[][2],    /* 2D contour */
                 gleDouble cont_normal[][2], /* 2D contour normals */
                 gleDouble up[3],           /* up vector for contour */
                 gleDouble startz,          /* start of segment */
                 gleDouble endz,            /* end of segment */
                 gleDouble twist);          /* number of rotations */

  Draws screw-type shapes. Takes a contour, and extrudes it along the z-axis, from a start z value of startz to an end z-value of endz. During the extrusion, it will spin the contour along the contour origin by twist degrees.

## GL3.2/IrisGL Subroutines

This library can be compiled for GL/IrisGL version 3.2 or above, or for OpenGL. The names of the subroutines are different for the GL/IrisGL and OpenGL versions. The are:

extrusion
  gleExtrusion
setjoinstyle
  gleSetJoinStyle
getjoinstyle
  gleGetJoinStyle
polycone
  glePolyCone
polycylinder
  glePolyCylinder
super_extrusion
  gleSuperExtrusion
twist_extrusion
  gleTwistExtrusion
spiral
  gleSpiral
lathe
  gleLathe
helicoid
  gleHelicoid
toroid
  gleToroid
screw
  gleScrew

## Stunts

For wire-frame mode, try using the glPolygonMode() routine.

## The End