=head1 NAME

B<glodInsertArrays> - A direct analog of the OpenGL vertex array
mechanism, this takes your current GL vertex array state and uses it
as a particular patch within GLOD

=cut

=head1 C SPECIFICATION

void B<glodInsertArrays>(I<GLuint name>, I<GLuint> patchname,
                      I<GLenum> mode, I<GLint> first, I<GLsizei> count,
                      I<GLuint> level, I<GLfloat> geometric_error)

=cut

=head1 PARAMETERS

=over

=item I<name> 

The name of the object to insert this patch into

=item I<patchname> 

The name of this patch. Note that patch names B<do not have to be
sequential>.

=item I<mode> 

Type of primitives to create. Currently supported is
B<GL_TRIANGLES>. Other triangle and polygon formats can be added given
demand.

=item I<first> 

The first vertex to start on. If you want to skip the first n
triangles, set first to be 3*n.

=item I<count> 

The number of B<vertices> to draw.

=item I<level> 

If you are manually creating a Discrete LOD object, then this
parameter specifies the discrete LOD level for this patch. The finest
level of a discrete object is 0. For hierarchy build types besides
B<GLOD_DISCRETE_MANUAL>, this should be set to 0.

=item I<geometric_error> 

When manually creating a Discrete LOD object, this paramater specifies
the error associated with this patch. For hierarchy build types besides
B<GLOD_DISCRETE_MANUAL>, this should be set to 0.

=back 


=head1 DESCRIPTION

As described in the GLOD overview, GLOD objects consist of
multiple patches. These patches are inserted into GLOD using
either this call or the InsertElements call. This call behaves
identically to glDrawArrays except that rather than drawing all of
the enabled pointers, they are copied into GLOD for later
simplification.

Following a call to this function, you can modify or delete the contents of the
your pointers as you wish.

B<Note that:>

=over

=item *

You must glEnable GL_VERTEX_ARRAYS for this to function properly

=item * 

For every pointer that you enable, including the vertex
pointer, you must both

=over

=item *

enable the corresponding <GL_<type>_> state, using B<glEnableClientState>

=item *

call the correct gl<type>Pointer function to set the pointer data and stride information

=back


=back


=head1 USAGE

Imagine we have two tighly packed arrays of C<3*num_tris> C<vertices> and C<normals>. We
insert this geometry into GLOD using the following code:

  // provided before
  int num_tris;
  GLfloat* vertices;
  GLfloat* normals;

  // initialize vertex arrays
  glEnableClientState(GL_VERTEX_ARRAY);
  glEnableClientState(GL_NORMAL_ARRAY);
  glVertexPointer(3, GL_FLOAT, 0, vertices);
  glNormalPointer(GL_FLOAT, 0, normals);

  // add them to GLOD
  glodNewObject(MY_OBJ_NAME, MY_GROUP_NAME);
  glodInsertArrays(MY_OBJ_NAME, 0,
                   GL_TRIANGLES, 0, 3*num_tris,
                   0,0.0);


=head1 ERRORS

=over

=item B<GLOD_INVALID_NAME> is generated if an object of the specified \c name does not exist

=item B<GLOD_INVALID_STATE> is generated if this object has already been built into a hierarchy

=item B<GLOD_INVALID_DATA_FORMAT> is generated if the current vertex array is in an unacceptable or unsupported format for GLOD to import from.

=back

=cut
