track app-shadertoy API requirements

[devel-chm]

These OpenGL routines are used in app-shadertoy but should be ok since they don't have any pointer arguments:

glActiveTexture
glAttachShader
glBindBuffer
glBindTexture
glBindVertexArray
glClear
glCompileShader
glCreateProgram
glCreateShader
glDeleteProgram
glDeleteShader
glDetachShader
glDisableVertexAttribArray
glDrawArrays
glEnableVertexAttribArray
glFlush
glGetError
glLinkProgram
glPixelStorei
glProgramUniform1f
glProgramUniform1i
glProgramUniform2f
glProgramUniform3f
glProgramUniform4f
glReadBuffer
glTexParameteri
glTexStorage2D
glUseProgram

These are the problematic routines with pointer arguments or return values.
We should sort out the API issues as regards these functions first:

glGetString
glBufferData
glGenBuffers
glGenTextures
glGenVertexArrays
glGetActiveUniform
glGetAttribLocation
glGetIntegerv
glGetProgramiv
glGetShaderiv
glNamedBufferData
glObjectLabel
glProgramUniform4fv
glProgramUniformMatrix4fv
glReadPixels
glShaderSource
glTexImage2D
glTexSubImage2D
glVertexAttribPointer

NOTE: arguments or return values with string pointers in them are probably ok since the binding for all pointers is to perl PV strings.

[wchristian]

The functions used in Microidium and not directly from ::Modern are as follows.

From Helpers:

glGetShaderInfoLog_p
glGetProgramInfoLog_p
glGetVersion_p

Also used in shadertoy:

glGetIntegerv_p
glGetAttribLocationARB_p
glGenTextures_p
glBufferDataARB_p
glGenBuffersARB_p
glGenVertexArrays_p
glShaderSourceARB_p
glGetShaderiv_p
glGetProgramiv_p
glTexImage2D_c
glVertexAttribPointerARB_c

Only in Microidium:

glGetUniformLocationARB_p
glGenFramebuffersEXT_p
glTexImage3D_c
glTexSubImage3D_c

Are in ::Modern, but have different prototypes, and thus can't accept arguments as @arrays:

glUniform2fARB
glUniform4fARB

[wchristian]

Forgot, for reference, here's the code where i'm using these functions:

https://github.com/wchristian/Microidium/blob/560852302b7047feeed8cb2b54296a929fd9b86e/lib/Microidium/SDLRole.pm#L22-L25

That should help in deciding which ones to implement, and which ones to give me guidance on how to replace them with other invocations.

[devel-chm]

For reference, these macros and functions are used by Prima::OpenGL:

GL_ALPHA
GL_BGR
GL_BLUE
GL_BYTE
GL_COLOR_BUFFER_BIT
GL_COLOR_INDEX
GL_DEPTH_COMPONENT
GL_FLOAT
GL_GREEN
GL_INT
GL_LUMINANCE
GL_LUMINANCE_ALPHA
GL_PACK_ALIGNMENT
GL_PACK_ROW_LENGTH
GL_POLYGON
GL_RED
GL_RGB
GL_RGBA
GL_SHORT
GL_STENCIL_INDEX
GL_UNSIGNED_BYTE
GL_UNSIGNED_INT
GL_UNSIGNED_SHORT

glBegin
glClear
glClearColor
glColor3f
glDrawPixels
glDrawPixels_c
glEnd
glFinish
glFlush
glOrtho
glPixelStorei
glReadPixels
glReadPixels_c
glVertex2f
glViewport

glXCreateContext

[wchristian]

Migrated most old OpenGL functions to OpenGL::Modern, with the changes i made being as follows:

In Microidium: wchristian/Microidium@7399ea8
In OpenGL::Modern::Helpers: wchristian/OpenGL-Modern@dd96555

Almost everything worked decently fine, though i'm unsure about the performance of so much data munging in Perl, especially when previously i could just hand C pointers to the XS code.

Additionally, as noted in #15, i couldn't migrate two functions due to the inability to pass them null pointers.

I also made slight adaptations to the "pass a pointer and the result will be written to it" functions, as some of them will write arrays of values to the given pointer. I added a "result count" argument to those, that defaults to 1 if not given, which is then used to set up the target buffer at the correct size.

[wchristian]

As recommended by @devel-chm i changed the typemap of const void *, fixed up the Helpers call of glBufferData and was able to remove the last OpenGL.pm imports due to being able to pass null pointers to texture functions.

wchristian/OpenGL-Modern@37fe97b
wchristian/Microidium@2e9babb

[devel-chm]

I've consolidated the required OpenGL API bindings from Microidium, Prima::OpenGL, PDL, and app-shadertoy into the attached file required-api.txt. I'm assuming that the OpenGL constants implementation is good so all the GL_DEFINE_PARAMS are good in OpenGL::Modern.

Regarding the function implementations, functions having only non-pointer/non-C-array argument types and return values should be correctly implemented with the standard default XS typemaps. I call those "good" and list them in the attached file required-api-good.txt.

The problematic bindings are the ones where there is a pointer type involved (this can be either a pointer in the C type specification, like "void*" or a C array specification which can be considered equivalent to a pointer type specification, like "data[5]". Because meaning of a pointer type in the API bindings is not fully determined by the type specification, the default binding will use the pointer types explicitly and leave the correct handling from perl to the perl programmer. Because the number and type of arguments and returns will be identical with the C API, these perl bindings are indicated by a suffix of "_c" on the base OpenGL function name.

I'm in the process of updating the generate-XS.pl program to apply the appropriate suffix to the function names in the bindings. Once that is complete and verified, work will continue with the more natural perl-ish bindings in 2 basic categories: enabling the use of perl @arrays where possible, and/or using a perl object or reference type to provide the data to be passed for the pointer arguments. The table below shows the current status of the bindings for the "bad" routines.

OpenGL Routine	Status	OpenGL Feature	#ptrs
glBufferData	_c done	GL_VERSION_1_5	1
glBufferDataARB_p	TODO	GL_ARB_vertex_buffer_object	1
glDrawPixels_c	_c done	GL_VERSION_1_1	1
glGenBuffers	_c done	GL_VERSION_1_5	1
glGenBuffersARB_p	TODO	GL_ARB_vertex_buffer_object	1
glGenFramebuffers	_c done	GL_ARB_framebuffer_object	1
glGenFramebuffersEXT_p	TODO	GL_EXT_framebuffer_object	1
glGenTextures	_c done	GL_VERSION_1_1	1
glGenTextures_p	TODO	GL_VERSION_1_1	1
glGenVertexArrays	_c done	GL_ARB_vertex_array_object	1
glGenVertexArrays_p	TODO	GL_ARB_vertex_array_object	1
glGetActiveUniform	_c done	GL_VERSION_2_0	4
glGetAttribLocation	_c done	GL_VERSION_2_0	1
glGetAttribLocationARB_p	TODO	GL_ARB_vertex_shader	1
glGetIntegerv	_c done	GL_VERSION_1_1	1
glGetIntegerv_p	TODO	GL_VERSION_1_1	1
glGetProgramInfoLog_p	TODO	GL_VERSION_1_1	1
glGetProgramiv	_c done	GL_VERSION_2_0	1
glGetProgramiv_p	TODO	GL_VERSION_2_0	1
glGetShaderInfoLog_p	TODO	GL_VERSION_2_0	2
glGetShaderiv	_c done	GL_VERSION_2_0	1
glGetShaderiv_p	TODO	GL_VERSION_2_0	1
glGetString	custom (in Modern.xs)	n/a	n/a
glGetUniformLocation	_c done	GL_VERSION_2_0	1
glGetUniformLocationARB_p	TODO	GL_ARB_shader_objects	1
glGetVersion_p	not in OpenGL API	n/a	n/a
glObjectLabel	_c done	GL_KHR_debug	1
glProgramUniform2v	glProgramUniform2v_c done	GL_ARB_separate_shader_objects	1
glProgramUniformMatrix4fv	_c done	GL_ARB_separate_shader_objects	1
glReadPixels	_c done	GL_VERSION_1_1	1
glReadPixels_c	_c done	GL_VERSION_1_1	1
glResizeBuffers	as glResizeBuffersMESA	GL_MESA_resize_buffers	0
glShaderSource	_c and _p done	GL_VERSION_2_0	3
glShaderSourceARB_p	TODO	GL_ARB_shader_objects	3
glTexGen[ifd]v	_c done	GL_VERSION_1_1	1
glTexImage1D	_c done	GL_VERSION_1_1	1
glTexImage2D	_c done	GL_VERSION_1_1	1
glTexImage2D_c	_c done	GL_VERSION_1_1	1
glTexImage3D_c	_c done	GL_VERSION_1_1	1
glTexSubImage2D	_c done	GL_VERSION_1_1	1
glTexSubImage3D_c	_c done	GL_VERSION_1_1	1
glVertexAttribPointer	_c done	GL_VERSION_2_0	1
glVertexAttribPointerARB_c	_c done	GL_ARB_vertex_program	1

required-api.txt
required-api-good.txt
required-api-bad.txt

[devel-chm]

I've determined that all the set of "good" routines includes all of the original Perl OpenGL non-suffixed routines so any remaining work for OpenGL::Modern is in the support of _c, _s, and _p bindings for the "bad" routines.

[devel-chm]

Implemented glShaderSource_p for the latest git and that routine works on SPP. Rather than spend time trying to hack perl to talk in C, I believe implementing real perl bindings that don't require finagling at the perl level to work at all is a better approach.

To add manual implementations, just edit utils/generate-XS.pl and add the routine name to @manual and then edit Modern.xs to place the new code near the bottom.

[devel-chm]

I've attached the extracted signatures from the priority routines and attached them here.
priority.txt

[devel-chm]

This is a list of OpenGL routines used by Slic3r. These appear to be done:

glBegin
glBindBufferARB
glBlendFunc
glClear
glClearColor
glClearDepth
glColor3f
glColor4f
glColorMaterial
glCullFace
glDepthFunc
glDisable
glDisableClientState
glDrawArrays
glEnable
glEnableClientState
glEnd
glFinish
glFlush
glLineWidth
glLoadIdentity
glMaterialf
glMatrixMode
glNormal3d
glOrtho
glPopMatrix
glPushMatrix
glRotatef
glShadeModel
glTranslatef
glVertex2f
glVertex3f
glViewport

and these are either '_c' currently and need friendly versions:

glBufferDataARB_p
glDeleteBuffersARB_p
glGenBuffersARB_p
glGetDoublev_p
glGetIntegerv_p
glLightModelfv_p
glLightfv_p
glMaterialfv_p
glMultMatrixd_p
glNormalPointer_c
glReadPixels_p
glVertexPointer_c