11.5.4  Opengl Binding Internals

(This section is mainly intended for maintainers working on the Mythryl Opengl binding, not applications programmers interested only in using it.)

The Mythryl Opengl binding architecture is based upon a four-layer stack:

• easy_opengl: High-level Mythryl application programmer functionality coded in Mythryl.
• opengl: Low-level Mythryl application programmer functionality coded in Mythryl.
• mythryl-opengl-library-in-main-process: Internal even lower-level functionality coded in Mythryl.
• mythryl-opengl-library-in-c-subprocess.c: Lowest level, written in C and calling the actual Opengl library routines.

To reduce the bug count and improve ease of maintenance, as much as practical of the Opengl binding is mechanically generated from compact specifications.

The generating Mythryl script is src/opt/opengl/sh/make-opengl-glue.

The specification file is src/opt/opengl/etc/opengl-construction.plan.

The make-opengl-glue script is normally invoked as needed by the top-level make compiler command; it may also be manually invoked by doing make opengl-glue at the top level.

A typical opengl-construction.plan paragraph looks like

    fn-name  : set_table_col_spacing 
    opengl-code : gtk_table_set_col_spacing( GTK_TABLE(/*table*/w0), /*col*/i1, /*spacing*/i2) 
    type     : { session: Session, table: Widget, col: Int, spacing: Int } -> Void 
    run      : plain-fn 
    url      : http://library.gnome.org/devel/gtk/stable/GtkTable.html#gtk-table-set-col-spacing 

This is a fairly dense encoding whose details are more significant and critical than is immediately apparent:

• fn-name gives the name of the Mythryl function seen by the application programmer.
• type gives the type of the Mythryl function seen by the application programmer.
• url if present points to the Opengl reference documentation on the relevant function.
• run specifies the make-opengl-glue function to be called to synthesize binding code. The other fields are in essence arguments to this function.
• opengl-code gives the actual C call to be made to the Opengl library.

  The parameter names w0, i1 and so forth are highly stylized:

  The first letter gives the parameter type according to the scheme

  • b: Boolean.
  • f: Float. (C double).
  • i: Int.
  • s: String.
  • w: Widget. (Internally coded on the Mythryl side as a small integer.)

  The second character in such parameter names gives the parameter number in the synthesized internal Mythryl low-level calls. Zero is first, and the the sequence must contain no gaps.

  A given parameter may appear more than once in the opengl code:

   
                      w0->style->bg_gc[ GTK_WIDGET_STATE(/*widget*/w0) ] 
                  

  Usually a comment immediately precedes each parameter name:

   
                      /*table*/w0 
                  

  If so, the identifier in the comment is used as the name of the parameter in synthesized low-level code, improving readability.

  A transformation function may be applied in the comment:

   
                      /*update_policy_to_int policy*/i1 
                  

  This function will be applied in the synthesized low-level Mythryl code, typically to translate from a Mythryl enum datatype like SHIFT_MODIFIER to a simple integer representation.

In some cases the needed translation from the Mythryl application programmer call to the driver level call is too irregular to be conveniently synthesized according to the above protocol. In such cases the code is simply manually provided inline in the spec:

    fn-name  : set_minimum_widget_size 
    opengl-code : gtk_widget_set_size_request( GTK_WIDGET(/*widget*/w0), /*wide*/i1, /*high*/i2) 
    type     : (Session, Widget, (Int,Int)) -> Void 
    run      : plain-fn 
    url      : http://library.gnome.org/devel/gtk/stable/GtkWidget.html#gtk-widget-set-size-request 
    opengl-client-g.pkg:        fun set_minimum_widget_size (session: Session, widget, (wide, high)) 
    opengl-client-g.pkg:            = 
    opengl-client-g.pkg:            d::set_minimum_widget_size (session.subsession, widget, wide, high);