search

LWJGL / lwjgl3

LWJGL is a Java library that enables cross-platform access to popular native APIs useful in the development of graphics (OpenGL, Vulkan, bgfx), audio (OpenAL, Opus), parallel computing (OpenCL, CUDA) and XR (OpenVR, LibOVR, OpenXR) applications.
https://www.lwjgl.org
BSD 3-Clause "New" or "Revised" License
4.67k stars 628 forks source link

Incorrect documentation for GLFW.glfwSet*Callback(long window, GLFW*CallbackI cbfun) #886

Closed SpinyOwl closed 1 year ago

SpinyOwl commented 1 year ago

Version

3.3.2

Module

GLFW

Bug description

The javadoc of set callback methods specifies that it returns previously set callback or null.

However, if we dive deeper to GLFW*Callback# createSafe we'll see that it returns newly created callback or null if function pointer is null.

Example: https://github.com/LWJGL/lwjgl3/blob/master/modules/lwjgl/glfw/src/generated/java/org/lwjgl/glfw/GLFW.java#L4117 https://github.com/LWJGL/lwjgl3/blob/master/modules/lwjgl/glfw/src/generated/java/org/lwjgl/glfw/GLFWMouseButtonCallback.java#L43 https://github.com/LWJGL/lwjgl3/blob/master/modules/lwjgl/glfw/src/generated/java/org/lwjgl/glfw/GLFWMouseButtonCallback.java#L34

Spasi commented 1 year ago

Hey @SpinyOwl,

LWJGL bindings include the native documentation, mostly as is. There is no "translation" to Java concepts used for wrapping the native functionality, except in rare cases where an technical/implementation detail can be tricky for Java developers. In this sense, the documentation for GLFW Set*Callback functions is accurate.

A new instance may indeed (but not always) be created for the previously set callback, because these functions return an abstract class type, not the corresponding interface type. However, this is a plain Java wrapper (cheap to allocate) over the native callback function (expensive to allocate). The returned instance can be used to free the native callback and there is no need to store callback instances in user code.