Clarification about `glGetSynciv` `bufSize` parameter

Does the bufSize parameter in glGetSynciv describe the count of integers, or the byte size of the integers? The documentation in the refpages is a bit confusing here. I’m not able to link to it from this forum, but it states: “glGetSynciv replaces up to bufSize integers in values with the corresponding property values of the object being queried”

I took a quick look around and noticed many projects are using either of these interpretations, so I was wondering which interpretation is correct.

For example, the book “OpenGL Programming Guide” states that it’s a byte size of the integers (“bufSize is the size (in bytes) of the buffer whose address is given in values”), while PyOpenGL assumes it’s a count of integers (“defaults to 1, maximum number of items to retrieve, currently all constants are defined to return a single value”).

I don’t see how that’s confusing. "bufSize integers" means exactly what it says. If it had said “5 integers”, then you wouldn’t be wondering if it meant 5 bytes or 5 integers, right?

Also, what is “OpenGL Programming”?

I also initially assumed it was a count of integers. But then I tried to verify this assumption by searching for some examples, and noticed many people using it either way (either as a count, or the size in bytes). So I think there is some confusion about which value to provide for this argument.

For example, there are a few examples by searching for glgetsynciv "sizeof(GLint)" in a search engine (including “OpenGL Superbible”). Other examples like PyOpenGL assume that a count is provided here.

Also bufSize is the same name used for other parameters that are measured in bytes which have the same description (“Specifies the size of the buffer whose address is given in values.”). For example, glGetProgramBinary specifies that its bufSize parameter is measured in bytes (“The maximum number of bytes that may be written into binary is specified by bufSize”)

Also, what is “OpenGL Programming”?

It’s the book “OpenGL Programming Guide: The Official Guide to Learning OpenGL” and it states bufSize is in bytes. I edited my post to clarify.

Yeah, you should pretty much never do that in OpenGL. There’s a lot of terrible code out there.

If you want to verify something, read the specification, not examples.

There is confusion on the part of users, likely because all other uses of bufSize as parameters are byte sizes. But the specification is quite clear on its meaning.

In general I agree, but I don’t think the statement in the specification is clear based on the amount of users misunderstanding this. “OpenGL Programming Guide” is an official resource that states it is a byte size, and its assumed to be a byte size in some glGetSynciv tests in the CTS for EGL.

Regardless I’ve assumed it’s a count of integers (not total byte size) for now. It looks like there was similar confusion for glGetInternalformativ in the past, which also suggests its a count.

Because of the use of the parameter name bufSize as a buffer size in bytes in nearly all OpenGL functions where it appears, I’ve filed this as an issue to have the name of the parameter changed to reflect its actual intended meaning.

1 Like