NAME

       OpenGL::Modern::Helpers - example usage of raw pointers from perl

WARNING

       This API is an experiment and will change!

OpenGL::Modern API Implementation

       This module exists to support the use of the OpenGL::Modern package for OpenGL bindings by documenting
       details of the implementation and giving example routines showing the use from perl.

   Implementation
       OpenGL::Modern is an XS module providings bindings to the C OpenGL library for graphics.  As such, it
       needs to handle conversion of input arguments from perl into the required datatypes for the C OpenGL API,
       it then calls the OpenGL routine, and then converts the return value (if any) from the C API datatype
       into an appropriate Perl type.

       Scalar Values

       Routines that take scalar values and return scalar values at the C level, are nicely mapped by the built
       in typemap conversions.  For example:

         GLenum
         glCheckNamedFramebufferStatus(GLuint framebuffer, GLenum target);

       where the functions takes two values, one an integer and one an enumeration which is basically an integer
       value as well.  The return value is another enumeration/integer value.  Since perl scalars can hold
       integers, the default XS implementation from perl would be prototyped in perl as

         $status = glCheckNamedFramebufferStatus($framebuffer, $target);

       or, taking advantage of the binding of all the OpenGL enumerations to perl constant functions we could
       write

         $status = glCheckNamedFramebufferStatus($framebuffer, GL_DRAW_FRAMEBUFFER);

       The key here is explicit scalar values and types which makes the XS perl implementation essentially the
       same at the C one just with perl scalars in place of C typed values.  Of the 2743 OpenGL API routines,
       1092 have scalar input and return values and can be considered implemented as is.

       Pointer Values

       The remaining OpenGL routines all have one (or more) pointer argument or return value which are not so
       simply mapped into perl because the use of pointers from C does not fully determine the use of those
       values:

       •   Pointers can be used to return values from routines

       •   Pointers can be used to pass single input values

       •   Pointers can be used to pass multiple input values

       •   Pointers can be used to return multiple input values

       The  current  XS implementation now represents non-char type pointers as the typemap T_PTR and the string
       and character pointers are T_PV.  The routines will be renamed with an added _c so as  to  indicate  that
       the mapping is the direct C one.

       These  _c  routines  closely  match  the  OpenGL C API but it requires that the perl user hand manage the
       allocation, initialization, packing and unpacking, etc for each function call.

       Please see this source file for the implementations of

         glGetShaderInfoLog_p
         glGetProgramInfoLog_p
         glGetVersion_p

         croak_on_gl_error

       showing  the  use   of   some   utility   routines   to   interface   to   the   OpenGL   API   routines.
       OpenGL::Modern::Helpers will be kept up to date with each release to document the API implementations and
       usage  as  the  bindings evolve and improve.  Once standardized and stable, a final version of Helpers.pm
       will be released.

perl v5.40.1                                       2025-03-27                       OpenGL::Modern::Helpers(3pm)