Dev:SundayMeetingAgenda/NewDev meetings/2009-12-06th

Doc pages we derived from it

• RNA explanation
• Operators explanation
• Blender's code file structure

NewDev Useful links

• Blender Architecture
• How to get involved

Meeting report

http://lists.blender.org/pipermail/bf-committers/2009-December/025396.html

NEW DEV MEETING 2009-12-06th

Mentors: ideasman42, theeth and DingTo
Log: http://blenderartists.org/~theeth/bf/meeting-newdev-09-12-06.txt

Agenda has been:

1. Decide if talk about 2.49 codebase or 2.5 only
2. Talking about C codebase or Python?
3. Mentorships
4. New devs interests?
5. Source code comments and documentation
6. General questions
  6.1 Blender architecture and how to grasp "the big picture"
  6.2 Finding things in the code
  6.3 RNA explanation
  6.4 Operators explanation


1. Decide if talk about 2.49 codebase or 2.5 only

  - We agreed not talking 2.4x code.

2. Talking about C codebase or Python?

  - majority wanted C, some C/python,

  - ideasman42 and theeth agreed that:
    - C/Python is very vague and it depends very much on where developers are
      interested in working, what problems they try to solve
     - also, in 2.5, it's not as clear cut as it used to be

  - ideasman42 asked if newdevs are more o C or python:
    - most are python/C or python with some basic C
    - one said to be C/C++

3. Mentorships

  - PapaSmurf asked whether experienced developers would like to mentor a new
    developer, like we did with GSOC: theeth showed interest :)

4. New devs interests?

  - kattkieru: armature and constraints systems, Python import/expoorter
  - amennelet would like to work on windows manager
  - djaddison: low level event handling
  - dmbasso/yoff: physics simulation, specifically muscle simulation -> Campbell
    answered this is too spesific area .
  - nfz: interested in "2.5 todo list and bug squashing"

  - Interesting note:
      <KAHR-Alpha>  isn't bullet C++?
      <ideasman42>  yes, but it has a C api. Not sure how effective that is though,
        only used the C++ api

5. Source code comments and documentation

  - matd would like to see important souce code files commented at the  beginning,
    in order to see what's a certain file for.
  - PapaSmurf and matd would liek to have _readme in each folder explaining the
    purpose fo the contents of that folder
    (at least in the root dir of all important modules like wm, rna, etc ...)

6. General questions

    6.1 BLENDER CODE ARCHITECTURE: "THE BIG PICTURE"

    - http://www.blender.org/development/architecture/
    - http://www.blender.org/community/get-involved/
    - (!!) theeth has patiently explained most of the folders in the code:
      http://wiki.blender.org/index.php/Dev:Doc/Blender_Source/Files_structure
    - Ideasman42 suggestion: "Not sure this is GOOD advice, but I found its good
      not even to try understand the big picture, just learn one area well".
      Theeth agrees.
    - DingTo started with UI scripts, expanded to RNA and Nodes, nfz too.
    - General agreement about starting from UI scripts or operators (in files
      ending in "_ops.c").
  
    6.2 FINDING THINGS IN CODE

    - Campbell asks how people searches in the code
      - cscope (kh_pylon)
      - code::blocks (nfz)
      - kscope, crep, http://wiki.blender.org/index.php/User:Ideasman42#crep (mindrones)

    6.3 RNA EXPLANATION
        (http://wiki.blender.org/index.php/Dev:Doc/Blender_Source/RNA)

      RNA is a data access and simple operations API. It sits on top of the low
      level C structs (called DNA).
      It's very basic stuff, like links between different structures, specific
      types and range of different members, ...
      From that, we generate the RNA Python API

      RNA defines not only the name of the property, also it sends an Notifier to
      tell Blender what has changed, and it contains the UI Text and Tooltip
      When you change that you also want blender to redraw for instance, or update
      its childrens location (childrens matrix)

      We dont want to define these update calls for anim/ui/py - so instead each
      access via rna: "ob.location" in python does an rna lookup, gets the array
      in C, the python api converts this known rna type to a vector and returns the value.
      Internally it does py -> coerce into an array -> rna array set function -> DNA array.
      Probably this is only interesying to py api devs.

      It might be interesting to note that RNA definition is split in two.
      A compile time generation and runtime code. In the RNA files, this is
      represented by #ifdef RNA_RUNTIME #ELSE #ENDIF

      If you ever want to look at rna code... you can mouse over the button and
      see its python variable, so if you mouse over object location youll get its
      python name, then search for "location", or "armature_head" or whatever...
      this is fairly easy way to find the rna code from a button (you can also just
      search for the tooltip which was people was used to do mostly in 2.4x)

      The rna code is in source/blender/makesrna/
      The file will start with rna_.

      If you use crep.sh, remember to add the ""'s or you'll get too
      many hits: for example if you look for "Full screen", you do:
      
      $ ./crep.sh "Full Screen"
      1 ./source/blender/editors/screen/screendump.c:177:       RNA_def_boolean(ot->srna, "full", 1, "Full Screen", "");
      2 ./source/blender/editors/screen/screendump.c:331:       RNA_def_boolean(ot->srna, "full", 1, "Full Screen", "");
      3 ./source/blender/editors/screen/screen_ops.c:1592:      ot->name = "Toggle Full Screen";
      4 ./source/blender/makesrna/intern/rna_scene.c:1387:              {R_OUTPUT_SCREEN, "SCREEN", 0, "Full Screen", "Images are rendered in full Screen"},
      enter a number to edit >

      Basically we have Notifiers and Listeners.
      RNA props send Notifiers and the different space types "listen" to those
      Notifiers and do an update/redraw
      
      Example and Questions
      -----------------------------------------------------------------------------
      So you have an objects location, which is: 

      // in DNA_object_types.h
      float location[3];

      but as well as this you want to access it from the UI and python and animations
      system of course: see the RNA counterpart below.

      Definition code:

      prop= RNA_def_property(srna, "location", PROP_FLOAT, PROP_TRANSLATION);
      RNA_def_property_float_sdna(prop, NULL, "loc");
      RNA_def_property_editable_array_func(prop, "rna_Object_location_editable");
      RNA_def_property_ui_text(prop, "Location", "Location of the object.");
      RNA_def_property_update(prop, NC_OBJECT|ND_TRANSFORM, "rna_Object_update");

      Q: Does this RNA specify 3 floats? Or is it not supposed to?
      A: RNA only references the 3 floats dna defines, the subtype PROP_TRANSLATION
          does that. For more generic arrays, the size has to be supplied.

      Q: so how does "ob.location = (x,y,z)" or whatever in Python update the DNA values?
      A: It runs the rna function to set the array from a python array that is converted,
          then it calls the RNA's update function which will trigger other updates
          if they are defined for that type.

      Q: Well wait, does that update function get generated automatically or do
          we have to write it? Is rna_object_update a function somewhere?
      A: It's done through the call to RNA_def_property_update. 
          In this case we have:
          RNA_def_property_update(prop, NC_OBJECT|ND_TRANSFORM, "rna_Object_update");

          - Thats a function at the beginning of the RNA file.
          - These NC_ and ND_ Notifiers are defined in wm_types.h, inside
            windowmanager code.
          - rna_Object_update is defined in the RUNTIME part of the code.

          NOTE:
          - You don't always need a function, so that can be NULL and only use
            notifiers flags.
          - Most of the time you dont needs to write your own update functions,
            or they can be added later if you get some redraw problems.. its not
            likely to break if they are not there...

      Q: So if you want to add a new type of object, do you just need to define
          RNA or also DNA?
      A: Defining new object types wasn't done in years and you'd also need to be
          familiar with reading and writing code in blender (readfile.c/writefile.c).
          Not suggested for beginners.

      -----------------------------------------------------------------------------

    6.4 OPERATORS EXPLANATION
        (http://wiki.blender.org/index.php/Dev:Doc/Blender_Source/Operators)

      Operators are tools.

      They're a very simple data structure with ID, descript and label strings,
      as well as a couple of function pointers and flags.
      The functions will be called when the operator is executed.

      The basics are exec, invoke, poll.

      EXEC
      It is called to apply the operator using only its parameters.
      
      INVOKE
      It is called when the operator runs interactively, when it needs user input
      (from a menu, mouse motion, ...)

      POLL
      This is called when the operator can be run in the current Context.
      The context is more or less the current state of the UI (where the pointer
      is, what's selected, ...), we'll talk about context later.
      For example the poll function is used to grey out buttons and menu entries.

      Exec and invoke are the functions that actually do stuff.
      For instance invoke() gets the mouse location, execute() assumes the input
      was alredy assigned as operator options.

      Generic poll functions also exist, you don't have to write your own.

      The operator definition can also include RNA properties, that are used as
      operator parameters.

      There are around 1000 operators at the moment: you can find out the complete
      list from the operator cheetsheet in the Help menu.

      NOTE ABOUT TEMPLATES
      If you want to get started with writing operators, there are python operator
      templates in the text templates menu, so you can start by loading the template.
      Running it, it wont appear in the menu but you can access it from the spacebar
      search.

      Example and Questions
      -----------------------------------------------------------------------------
      The make parent operator defines a property for parenting type.
      Its invoke function displays the parenting menu.
      Its exec reads the type from the properties and does whatever is needed.
      For operators that need a menu like that, we have a generic menu function
      that can be used.
      Here's the parenting operator:
      
      void OBJECT_OT_parent_set(wmOperatorType *ot)
      {
        /* identifiers */
        ot->name= "Make Parent";
        ot->description = "Set the object's parenting.";
        ot->idname= "OBJECT_OT_parent_set";

        /* api callbacks */
        ot->invoke= parent_set_invoke;
        ot->exec= parent_set_exec;

        ot->poll= ED_operator_object_active_editable;

        /* flags */
        ot->flag= OPTYPE_REGISTER|OPTYPE_UNDO;

        RNA_def_enum(ot->srna, "type", prop_make_parent_types, 0, "Type", "");
      }

      In this operator:
      - parent_set_invoke, parent_set_exec, and ED_operator_object_active_editable
        are functions.
      - prop_make_parent_types is an array of defined types
      - the flags are used to specify different behavior:
        - OPTYPE_REGISTER means it will be displayed in the last operator toolbar
        - OPTYPE_UNDO means it will set an undo point after it runs

      Q: Undo handled generically? (as it looks to be)
      A: Yes.

      Q: In this example function where do you get ahold of the Context.
      A: The context is passed as argument to the invoke, exec and poll function.
          - The event system will give you the correct context,
          - invoke gets the context, the operator structure and the caller event,
          - exec gets the context and the operator

      Q: Is there a difference between python operators and C operators apart from speed?
      A: No, the python operator creates an operator type struct when registered

      Q: What about for submitting to the code base?  Do the main devs prefer Python
          or C operators?
      A: Py defined operators are acceptable as patches tracker.
          https://projects.blender.org/tracker/?atid=127&group_id=9&func=browse