Page MenuHome

Python API (parent task)
Open, NormalPublic

Description

Parent task for Python API topics that need to be addressed before 2.80 can be released:

  • Draw API
    • gpu.selecthas no useful documentation. - can it be removed?
    • GPUShader is spread out between types and shader pages. Do we really need gpu.shader or could we just do something like gpu.types.GPUShader.FromBuiltin(...)? - Who decides that?
    • gpu.matrix is usable and documented but the benefit of using it instead of just setting the matrices directly when using builtin shaders is often unclear. I think many functions can be removed (like reset, pop, pop_projection, push, push_projection). For other functions the name could be changed (e.g. multiply_matrix and load_matrix are too generic names) - Who decides that?
    • batch_from_shader: add it to gpu instead of gpu_extras? - Who decides that?
  • Tools and Gizmo API
    • No API documentation yet.
  • Depsgraph API:
    • Missing API to export objects at render resolution. Needs function to get/clear render resolution depsgraph for a scene and view layer?
    • Missing docs explaining how the new depsgraph and COW affect Python scripts.
    • Scene update pre/post handlers: add back, but only run when active depsgraph actually changed?
  • Scenes and Objects API:
    • Missing docs:
      • Working with collections.
    • Missings examples:
      • Object mode operator working on selected, visible, editable objects
      • Mesh edit mode operator working on multiple objects.
    • Too difficult to set new collection as active: https://devtalk.blender.org/t/set-active-collection/2409
  • Example code
    • Verify API docs example still work
    • Broken text editor Python templates: Operator Mesh UV, Operator Modal Draw, Operator Modal View3D Raycast, UI Tool Simple
  • Hide bundled addons not updated to 2.8? rBa421cfa8d31d85c9e855788c25de4f37ef10ab34
    • It's confusing to have them show in the list, and throw and error when you try to enable them.
    • Some might never get updated.
    • User installed addons could still show

Details

Type
To Do

Event Timeline

Brecht Van Lommel (brecht) triaged this task as Normal priority.

About the Draw API:

  • I'll add more documentation for GPUVertBuf, GPUVertFormat and GPUIndexBuf. They are not needed in many cases though.
  • I have no idea what gpu.select is useful for. So I can't really help documenting it right now. Maybe we should just leave this module private for now.
  • Personally I find it a bit confusing to use the gpu.matrix module. It's unclear to me what I depend on when I use it. Unfortunately the module has to be used when you want to use the builtin shaders. I'd expect that Blender can derive the view/projection matrix from the context I just have to provide the model matrix. Not sure what's the best way to handle it.
  • Maybe gpu.shader could be merged with gpu.types.GPUShader? Ideally it would have something like this: gpu.types.GPUShader.FromBuiltin(...), shader.vertexcode, shader.fragcode and shader.geocode. This also means that we'd have to store the source code for user defined shaders, but that would not be too bad imo.
  • I'm waiting for one thing to get merged (namely D3918) and then I'll make a new, probably a bit shorter example for GPUOffScreen and put it on the main gpu module page. Personally I think large examples a the one currently provided are not useful because they 1) make it look way too hard and 2) force developers to strip away a lot of code to understand what is actually required to get it working.
  • I agree that it would be cool to have batch_for_shader in the gpu module directly but it feels like I'm not in a position to make that decision.