Update bgl docs
Needs ReviewPublic
Actions

Authored by Jacques Lucke (JacquesLucke) on Tue, Jan 29, 5:49 PM.

Details

Reviewers

Brecht Van Lommel (brecht)
Campbell Barton (campbellbarton)

Summary

The current bgl are outdated.
Instead of going through all functions and updating them, I just linked every function to the official documentation (as discussed in T60891).

The bgl docs should focus on how to use the normal OpenGL functions in Blender.
This can be achieved by providing some more examples.
However, I'd like to keep that separate from this patch.

The script to find all links:

import re
import bpy
import bgl
import requests
from pprint import pprint

def get_function_names_in_bgl():
    def gl_filter(name):
        return name.startswith("gl")
    return list(filter(gl_filter, dir(bgl)))

def get_function_links():
    link_prefix = "https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/"
    flat_index_html = requests.get(link_prefix + "indexflat.php").text

    links = {}

    for line in flat_index_html.splitlines():
        line = line.strip()
        match = re.match(r"<li><a href=\"(.*)\" target=\"pagedisplay\">(\w+)<", line)
        if match is None:
            continue

        file_name = match.group(1)
        function_name = match.group(2)
        links[function_name] = link_prefix + file_name

    return links


output_parts = []

function_links = get_function_links()
for function_name in sorted(get_function_names_in_bgl()):
    link = function_links[function_name]
    output_parts.append(f"- `{function_name} <{link}>`__")

output = "\n".join(output_parts)
print(output)

bpy.context.window_manager.clipboard = output

I put all functions in a list to reduce the line spacing.
That makes it much easier to scan through the list.

Diff Detail

Repository

rB Blender

Branch

bgl-docs (branched from master)

Build Status

Buildable 2847
Build 2847: arc lint + arc unit

Event Timeline

Jacques Lucke (JacquesLucke) created this revision.Tue, Jan 29, 5:49 PM

Harbormaster completed remote builds in B2797: Diff 13413.Tue, Jan 29, 5:49 PM

Jacques Lucke (JacquesLucke) edited the summary of this revision. (Show Details)Tue, Jan 29, 5:52 PM

While I'm all for reducing redundant information.
The issue with referencing external docs is the blender/python wrapper isn't *just* calling out to OpenGL,
There are enough cases where it handles arguments in a Blender specific way (bgl.Buffer mainly)

I think if we keep the API, we should keep the docs (and update them eventually),
or we can remove deprecated API's from both docs and bgl module.

Otherwise users are forced to lookup the source code to see how arguments are passed.

I think it would be nice if we could just provide a general signature translation rule from normal opengl to bgl. (pointers -> buffer)

Other exceptions can be mentioned on the page, I just don't know them all yet.
This is a wrapper, so we should use the docs to explain the wrapper and not the wrapped functionality (which has much better explanations already).

Agree on external links for more detailed docs.

I was thinking we could generate signatures from BGL_Wrap macro, however the issue with this is that it doesn't say what kind of buffer, which is useful in the existing docs.

If we wanted we could add some way to hint the type, but this becomes a hassle to maintain.

Since we only need to remove deprecated functions and the API doesn't change often, it could be simplest to write a basic validator (reports mismatch between docs and BGL module), then update occasionally.

Stripping down docstrings can be handled separately.

I could write a simple Python program that reads in bgl.c, finds all lines that start with BGL_Wrap and creates the .rst file with signatures.
Looks like these lines contain all the necessary information, no? E.g. GLuintP is just mapped to bgl.Buffer of bgl.GL_INT.
At the same time this script also finds all the links to the official documentation.

bgl docs from BLG_Wrap

I just wanted to try this, I know it looks ugly and lots of information is missing...
Will write the simple validator script next.

import re
import requests
from dataclasses import dataclass

@dataclass
class BglWrapper:
    name: str
    return_type: str
    argument_types: list

type_mapping = {
    "GLenum" : "Enumerated Constant",
    "GLbitfield" : "Enumerated Constant(s)",
    "GLfloat" : "float",
    "GLdouble" : "double",
    "GLint" : "int",
    "GLboolean" : "int (boolean)",
    "GLbooleanP" : "Boolean Buffer",
    "GLdoubleP" : "Double Buffer",
    "GLfloatP" : "Float Buffer",
    "GLintP" : "Int Buffer",
    "GLuintP" : "Unsigned Int Buffer",
    "GLsizei" : "int",
    "GLsizeiptr" : "...",
    "GLbyteP" : "Byte Buffer",
    "GLshort" : "int",
    "GLshortP" : "Short Buffer",
    "GLubyte" : "int",
    "GLubyteP" : "Unsigned Byte Buffer",
    "GLushortP" : "Unsigned Short Buffer",
    "GLuint" : "int",
    "GLstring" : "str",
    "GLintptr" : "Int Buffer",
    "GLvoidP" : "Buffer",
    "GLenumP" : "Enum P",
    "GLsizeiP" : "Sizei Buffer",
    "GLcharP" : "Char Buffer",
    "GLint64P" : "Int64 Buffer",
}

def iter_bgl_wrappers():
    for line in iter_bgl_wrap_lines():
        match = re.match(r"BGL_Wrap\((\w+),\s*(\w+),\s*\(([\w,\s]+)\)\);", line)
        wrapper = BglWrapper(
            name="gl" + match.group(1),
            return_type=match.group(2),
            argument_types=match.group(3).replace(" ", "").split(","))
        if wrapper.argument_types == ["void"]:
            wrapper.argument_types = []
        yield wrapper

def iter_bgl_wrap_lines():
    bgl_path = "/home/jacques/blender-git/blender/source/blender/python/generic/bgl.c"

    with open(bgl_path) as fs:
        bgl_file_content = fs.read()

    for line in bgl_file_content.splitlines():
        if line.startswith("BGL_Wrap"):
            yield line

def get_function_links():
    link_prefix = "https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/"
    flat_index_html = requests.get(link_prefix + "indexflat.php").text

    links = {}

    for line in flat_index_html.splitlines():
        line = line.strip()
        match = re.match(r"<li><a href=\"(.*)\" target=\"pagedisplay\">(\w+)<", line)
        if match is None:
            continue

        file_name = match.group(1)
        function_name = match.group(2)
        links[function_name] = link_prefix + file_name

    return links

def iter_documentation_lines():
    function_links = get_function_links()
    for wrapper in sorted(iter_bgl_wrappers(), key=lambda x: x.name):
        arguments = wrapper.argument_types
        if len(arguments) > 0:
            yield f".. function:: {wrapper.name}(...):"
        else:
            yield f".. function:: {wrapper.name}():"

        yield ""
        yield f"   `{wrapper.name} <{function_links[wrapper.name]}>`__"
        yield ""
        for i, argument in enumerate(arguments, 1):
            yield f"   :arg {i}: "
            yield f"   :type {i}: {type_mapping[argument]}"
        if wrapper.return_type != "void":
            yield f"   :rtype: {wrapper.return_type}"
        yield ""

documentation = "\n".join(iter_documentation_lines())

print(documentation)

Harbormaster completed remote builds in B2847: Diff 13527.Wed, Feb 6, 1:43 PM

The arguments no longer have names, assume this is what you mean by lots of information is missing... - if it can be extended to be about as good as what we have, dont see why not use it.

Then again, we could just remove redundant information and hand maintain (perhaps with validator that lets us know when there is a mis-match) it since OpenGL isn't changing that often, our BGL module less often.

Revision Contents
Changeset List

			Path	Packages
M			doc/python_api/rst/bgl.rst (3653 lines)

Diff	ID	Base	Description	Created	Lint	Unit
Base			Base
Diff 1	13413	33dcf9f		Tue, Jan 29, 5:49 PM	★	★
Diff 2	13527	4547815	- bgl docs from BLG_Wrap	Wed, Feb 6, 1:43 PM	★	★

Commit	Tree	Parents	Author	Summary	Date
3c2f102d3dfa	29dcefd2aee7	9675ce0ec7f3	Jacques Lucke	bgl docs from BLG_Wrap	Wed, Feb 6, 1:42 PM
9675ce0ec7f3	8c2a39214a37	45478158479d	Jacques Lucke	Update bgl docs (Show More…)	Tue, Jan 29, 5:35 PM

Diff 13527

View Options

doc/python_api/rst/bgl.rst

Update bgl docsNeeds ReviewPublicActions