search

KhronosGroup / OpenGL-Registry

OpenGL, OpenGL ES, and OpenGL ES-SC API and Extension Registry
677 stars 274 forks source link

Renamed "cap" parameter of "glEnable", "glDisable", "glIsEnabled" commands to "target" #593

Open Rytis-Stan opened 10 months ago

Rytis-Stan commented 10 months ago

The renaming was done to be consistent with "glEnablei", "glDisablei" and "glIsEnabledi" commands (both in this XML and in the specification PDFs). Note that the parameter of "glIsEnabled" command should technically be called "value" (according to the specification PDFs), but it was renamed to "target" for sake of consistency among all the related commands. Alternatively, it can be renamed to "value" again to completely match the specifications

Rytis-Stan commented 10 months ago

The naming is quite chaotic even in the documentation pages, which use the "cap" name. For example: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glEnable.xhtml https://registry.khronos.org/OpenGL-Refpages/gl2.1/xhtml/glEnable.xml

Would be great to fix the naming everywhere consistently. Besides the naming mismatches in different places, there seems to be a tension of what naming system to use. Ideally, everything should match the specifications. But keeping naming consistent among related commands would also be great.

If anyone has suggestions on how to best approach this, comments would be welcome.

SunSerega commented 10 months ago

Well, if the parameter is consistently target now (tho in some places, like glDisableClientState - it's array) - then the group EnableCap should also get renamed...

Rytis-Stan commented 10 months ago

Well, if the parameter is consistently target now (tho in some places, like glDisableClientState - it's array) - then the group EnableCap should also get renamed...

Any suggestions on how to rename EnableCap?

SunSerega commented 10 months ago

I was thinking the same way, from EnableCap to EnableTarget - to use the same term.

Rytis-Stan commented 10 months ago

@SunSerega - Renamed EnableCap to EnableTarget. Not sure if array parameters should be renamed (the name target sounds better to me than array, but array is the name used in the specification PDFs).

SunSerega commented 10 months ago

I would suggest reverting the group changes until https://github.com/KhronosGroup/OpenGL-Registry/issues/481 is in place.

Wouldn't that be a time when improvements like these would be impossible for sure? And even if not, #481 has been silent for a while...

Perksey commented 10 months ago

Not really, we can decide that we want to break everything, but that has to be a decision made collectively. It is irresponsible to knowingly break potentially hundreds of downstream projects without publishing formal documentation saying we reserve the right to do so. That is what #481 is about.

Rytis-Stan commented 9 months ago

@Perksey - What would be your suggestion for this PR? To just rename parameters? Or to keep this PR on hold until https://github.com/KhronosGroup/OpenGL-Registry/issues/481 has come to a conclusion?

Perksey commented 9 months ago

I think it would be irresponsible to go ahead with this PR unless we have set a precedent for doing so per #481. If there is particular desire from contributors to go ahead with changes like these, I'd recommend such contributors work with the necessary stakeholders to drive #481 to consensus.

SunSerega commented 9 months ago

Fair enough... I have a lot of doubts about continuing things like #543 - having guidelines would solve that, one way or another. But as it is, I feel powerless about #481. I mean, I voiced my stance on it... Which, honestly, feels far from the consensus. And maybe a bit overly dramatized, the way I put it. But even without that - what else can I do? I don't think it's a solution to keep bugging people pinged in the header of #481. I guess we are still just waiting for more of them to react?

NogginBops commented 9 months ago

If people have had more than 2 years to respond to a ping I think we can assume they are not going to reply. I personally think we should set a goal where we want the enum groups to be in terms of consistency, correctness and expressiveness, and then we can evaluate enum group work according to if that gets us towards the goal of how we want the enums to behave.

In my own bindings I'm likely going to implement a translation table for enum group names so that I can rename them myself to remain "backwards compatible", won't fix members being added or removed but yeah I think that if you are using the latest gl.xml from the registry I think you should "expect" breakages.