OpenGL::Modern::Helpers - example usage of raw pointers from perl
This API is an experiment and will change!
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.
OpenGL::Modern is an XS module providings bindings to the C OpenGL library for graphics. As such, it needs to handle conversion of input arguements 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.
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.
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.