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

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.