API change warning

[spasi]

I've just committed a change that will affect LWJGL's alternative GL functions that return primitive types. The change will add the original type postfix to the method name, hence breaking existing apps that are compiled against previous builds. An example for GL15.glGetBufferParameter:

// Original C function signature
typedef void (APIENTRY *glGetBufferParameterivPROC) (GLenum target, GLenum pname, GLint * params);

// LWJGL method signature
public static void glGetBufferParameter(int target, int pname, IntBuffer params);

// LWJGL alternative method signature:
public static int glGetBufferParameter(int target, int pname);

The change modifies the last signature like so:

// LWJGL alternative method signature (new):
public static int glGetBufferParameteri(int target, int pname);

The 'i' is added at the end, just like glVertex3f has an 'f' there. The reason for the change is that future GL version/extension often add new versions of such functions that return different types. This is problematic when both versions are statically imported, there's no way to distinguish between them and you end up having to specify the class before the method.

I'm hoping that this won't affect too many users. If it causes serious problems, please post here and I'll consider rolling back the change.

[ra4king]

Is this a good idea before 3.0? Do you have a list of all the changed functions?

[spasi]

Probably not a good idea indeed and I will roll it back if people have trouble from it. Personally the changes don't affect me because I can afford to recompile my code with the necessary changes, but that's not true for everyone. Anyway, keep in mind that this only affects people that use the alternative/convenient methods, the normal GL functions remain unchanged.

The change list (names are as they appear in C signatures):

GL15.glGetBufferParameteriv
GL15.glGetQueryiv
GL20.glGetShaderiv
GL20.glGetProgramiv
GL30.glGetRenderbufferParameteriv
GL30.glGetFramebufferAttachmentParameteriv
GL31.glGetActiveUniformsiv
GL31.glGetActiveUniformBlockiv
GL32.glGetBufferParameteri64v
GL32.glGetSynciv
GL33.glGetQueryObjecti64v
GL33.glGetQueryObjectui64v
GL40.glGetActiveSubroutineUniformiv
GL40.glGetUniformSubroutineuiv
GL40.glGetProgramStageiv
GL40.glGetQueryIndexediv
GL41.glGetProgramPipelineiv
GL43.glGetFramebufferParameteriv
GL43.glGetInternalformati64v
GL43.glGetProgramInterfaceiv

ARB_buffer_object.glGetBufferParameterivARB
ARB_framebuffer_no_attachments.glGetFramebufferParameteriv
ARB_framebuffer_object.glGetRenderbufferParameteriv
ARB_framebuffer_object.glGetFramebufferAttachmentParameteriv
ARB_internalformat_query2.glGetInternalformati64v
ARB_occlusion_query.glGetQueryivARB
ARB_program.glGetProgramivARB
ARB_program_interface_query.glGetProgramInterfaceiv
ARB_separate_shader_objects.glGetProgramPipelineiv
ARB_sync.glGetSynciv
ARB_shader_subroutine.glGetActiveSubroutineUniformiv
ARB_timer_query.glGetQueryObjecti64v
ARB_timer_query.glGetQueryObjectui64v
ARB_transform_feedback3.glGetQueryIndexediv
ARB_uniform_buffer_object.glGetActiveUniformsiv
ARB_uniform_buffer_object.glGetActiveUniformBlockiv

EXT_framebuffer_object.glGetRenderbufferParameterivEXT
EXT_framebuffer_object.glGetFramebufferAttachmentParameterivEXT

APPLE_object_purgeable.glGetObjectParameterivAPPLE

ATI_vertex_array_object.glGetObjectBufferivATI

NV_present_video.glGetVideoivNV
NV_present_video.glGetVideouivNV
NV_video_capture.glGetVideoCaptureivNV
NV_program.glGetProgramivNV
NV_shader_buffer_load.glGetBufferParameterui64vNV
NV_shader_buffer_load.glGetNamedBufferParameterui64vNV
NV_shader_buffer_load.glGetIntegerui64vNV
NV_vertex_buffer_unified_memory.glGetIntegerui64i_vNV

[ra4king]

The biggest ones are glGetShaderiv and glGetProgramiv since those are a must for error-checking. This will break all applications using shaders :S

I say only add that primitive type letter to the new functions that have different parameters.

[princec]

Absolutely don't care. Trivial to fix source and recompile. Anybody who whines otherwise can f*ck off and use JOGL*

Cas

* Been drinking. Bad mood.

[spasi]

I figured both the old and new versions can coexist so I restored the old versions and added deprecation warnings. Like this:

public static void glGetShader(int shader, int pname, IntBuffer params) {
	...
}

/**
 * Overloads glGetShaderiv.
 * <p>
 * @deprecated Will be removed in 3.0. Use {@link #glGetShaderi} instead. 
 */
public static int glGetShader(int shader, int pname) {
	return GL20.glGetShaderi(shader, pname);
}

/** Overloads glGetShaderiv. */
public static int glGetShaderi(int shader, int pname) {
	...
}

I didn't restore everything, GL41+ and newest extensions will have the new versions only. Let me know if that's a problem for anyone.

[ra4king]

That's perfect, thanks!