Matlab's HG2 mechanism

A few days ago I posted ^[1] a lengthy article about Matlab’s undocumented feature function. In it, I mentioned a feature called HG2, that I believe merits a dedicated article, due to its potential high impact on future Matlab releases.
HG2, which presumably stands for “Handle Graphics 2nd generation”, was already reported in the past as an undocumented hidden figure property ^[2] (UseHG2). In normal Matlab usage, this boolean property is ‘off’:

>> get(gcf,'usehg2')
ans =
off

HG2 is mentioned in quite a few Matlab files:

• clf.m, hgload.m, ishg2figure.m, datetick.m, linkdata.m, linkplotfunc.m, cameratoolbar, /bin/registry/handle_graphics.xml, /ja/xlate and many more
• uimodemanager.m (and others) temporarily disables a ‘MATLAB:handle:hg2’ warning
• defaulterrorcallback.m mentions ‘MATLAB:HG2:SceneNode’ and ‘MATLAB:HG2:Property’
• getplotbrowserproptable.m mentions several special HG2 types (hg2.Line, hg2.Lineseries, hg2.Patch etc.)
• There’s even a dedicated /toolbox/matlab/graphics/private/ishg2figure.m function that determines whether a figure contains any HG2 graphics based on the existence of ‘hg2peer’ appdata (getappdata(fig,’hg2peer’)).
• /toolbox/matlab/plottools/@objutil/@eventmanager/schema.m (and a few others) has the following comment:

   % may contain either UDD or MCOS listeners during the hg2 migration.

Obviously, much effort was invested in HG2 functionality. The fact that HG2 has been under development at least since 2007 (when I first discovered and reported ^[3] it) seems to indicate a major upheaval in Matlab’s Handle Graphics mechanism. This hunch is reinforced by cryptic comments made by MathWorks personnel over the past few years that they are indeed looking at the HG system, which in their opinion is nearing its limitations. Perhaps I’m mixing unrelated stuff here, but it does make sense in light of Matlab’s push of its OOP class system over the past few releases.
To preview this HG2 system, we need to turn it on. Unfortunately, when we set the figure’s UseHG2 to ‘on’ there doesn’t seem to be any visible effect. However, this changes after we use the corresponding ‘UseHG2’ feature using the feature function (this caused lots of nasty-looking errors in past releases but works ok in R2010a):

>> feature('usehg2',1)

The /ja/xlate file (which is used in conjunction with the undocumented xlate function to translates Matlab messages from English to Japanese) has another key to unlocking HG2: This file contains the following message: “feature(‘useGBT2’) is only available when Matlab is started with -hgVersion 2 option.“. So let’s do as the xlate message advises and start a new Matlab session with the undocumented “-hgVersion 2” command-line option. Now feature(‘usehg2’) is true by default and we can test the HG2 system.
Matlab looks basically the same in HG2 as in HG1. All the regular graphic functions behave just as we would expect from the existing (HG1) implementation. There are two major differences though:

• the figure toolbars/menubars are missing and cannot be shown, even when the relevant figure properties are set. Without a menubar and toobar, Matlab figures are extremely less useful than their HG1 counterparts. This problem does not occur in HG2-enabled figures in the regular Matlab session (i.e., without using the “-hgVersion 2” command-line option)
• all the HG handles are now Matlab class handles rather than numeric values (These class handles are similar to those returned today (in HG1) using the undocumented handle function). There’s an exception to this rule: in regular Matlab sessions (i.e., without using the “-hgVersion 2” command-line option), after setting the ‘UseHG2’ feature on, the returned figure handle is numeric rather than a class handle (but if you now plot within this figure you get the class object handles). Here’s the output from the “-hgVersion 2” Matlab session:

  >> hFig = figure
  hFig =
  	ui.Figure
  >> hLine = plot(1:5)
  hLine =
  	hg2.Lineseries
  >> get(hLine,'Parent')
  ans =
  	hg2.Axes
  >> findprop(gcf,'Tag')
  ans =
    meta.property handle
    Package: meta
    Properties:
                     Name: 'Tag'
              Description: 'Tag PropInfo'
      DetailedDescription: ''
                GetAccess: 'public'
                SetAccess: 'public'
                Dependent: 1
                 Constant: 0
                 Abstract: 0
                Transient: 0
                   Hidden: 0
            GetObservable: 1
            SetObservable: 1
                 AbortSet: 0
                GetMethod: []
                SetMethod: []
               HasDefault: 0
            DefiningClass: [1x1 meta.class]
    Methods, Events, Superclasses
  >> methods(gcf)
  Methods for class ui.Figure:
  Figure                  disp                    get                     horzcat                 lt                      subsasgn
  addlistener             double                  getParentImpl           ishghandlewithargs      ne                      vertcat
  addprop                 eq                      getSceneViewer          ishghandlewoargs        notify
  applydefaultproperties  findobj                 getdisp                 isvalid                 reset
  cat                     findprop                gt                      java                    set
  delete                  ge                      hgclose                 le                      setdisp
  Static methods:
  getDefaultObject
  >> methods(gcf,'-full')
  Methods for class ui.Figure:
  ui.Figure lhs1 Figure(rhs0)
  event.listener L addlistener(handle sources, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
  event.proplistener L addlistener(handle sources, meta.property propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
  event.proplistener L addlistener(handle sources, string propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
  event.proplistener L addlistener(handle sources, cell propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
  meta.property prop addprop(handle scalar object, string propname)  % Inherited from dynamicprops
  applydefaultproperties(HGHandle object, rhs1)  % Inherited from hg2utils.HGHandle
  HeterogeneousHandle lhs3 cat(double rhs0, rhs1, rhs2)  % Inherited from HeterogeneousHandle
  delete(handle obj)  % Inherited from handle
  disp(object)  % Inherited from hg2utils.HGHandle
  lhs1 double(handle object)  % Inherited from hg2utils.HGHandle
  logical TF eq(A, B)  % Inherited from hg2utils.HGHandle
  handle output findobj(handle object, varargin)  % Inherited from hg2utils.HGHandle
  meta.property prop findprop(handle scalar object, string propname)  % Inherited from handle
  logical TF ge(A, B)  % Inherited from handle
  varargout get(hgsetget object, rhs1)  % Inherited from hg2utils.HGHandle
  Static HeterogeneousHandle lhs0 getDefaultObject  % Inherited from hg2utils.HGHandle
  lhs2 getParentImpl(handle scalar object, rhs1)  % Inherited from hg2utils.HGObject
  lhs2 getSceneViewer(handle scalar object, rhs1)  % Inherited from ui.UISceneViewerParent
  getdisp(hgsetget rhs0)  % Inherited from hgsetget
  logical TF gt(A, B)  % Inherited from handle
  hgclose(handle scalar object)
  HeterogeneousHandle lhs2 horzcat(rhs0, rhs1)  % Inherited from HeterogeneousHandle
  lhs2 ishghandlewithargs(handle scalar object, rhs1)  % Inherited from hg2utils.HGObject
  lhs1 ishghandlewoargs(handle scalar object)  % Inherited from hg2utils.HGObject
  logical validity isvalid(handle obj)  % Inherited from handle
  j java(JavaVisible scalar h)  % Inherited from JavaVisible
  logical TF le(A, B)  % Inherited from handle
  logical TF lt(A, B)  % Inherited from handle
  logical TF ne(A, B)  % Inherited from hg2utils.HGHandle
  notify(handle sources, string eventname, event.EventData scalar eventdata)  % Inherited from handle
  notify(handle sources, string eventname)  % Inherited from handle
  reset(handle scalar object)  % Inherited from hg2utils.HGHandle
  varargout set(hgsetget object, rhs1)  % Inherited from hg2utils.HGHandle
  setdisp(hgsetget rhs0)  % Inherited from hgsetget
  varargout subsasgn(rhs0, rhs1, rhs2, rhs3)  % Inherited from HeterogeneousHandle
  HeterogeneousHandle lhs2 vertcat(rhs0, rhs1)  % Inherited from HeterogeneousHandle
  

The latest Matlab releases have shown how the Matlab handle class can be extended using user-created derived classes. It stands to reason that so do all the new HG2 objects. This would theoretically enable Matlab programmers to customize graphic objects appearance to suit their needs in a more intuitive manner than possible using HG1.
Many mysteries remain:

• is it possible to mix HG1 and HG2 objects in the same figure?
• can we switch between HG1 and HG2 in the same Matlab session (I got some crashes…)?
• why is there a need for the separate feature options ‘UseHG2’, ‘UseGBT2’ and ‘HGUsingMatlabClasses’?
• why is there a need for “-hgVersion 2” Matlab sessions if we can simply use feature(‘UseHG2’)?
• is it possible to restore the figure menubar and toolbar in “-hgVersion 2” Matlab sessions?
• is it indeed possible to extend HG2 objects using user-defined classes? and if so, can we modify the appearance/behavior beyond what is available in the existing list of HG2 properties?
• beyond changing numeric handles into class handles, are there any actual benefits to the HG2 system over HG1?
• what is the difference between HG2, GBT2 and GBT1.5 (which are mentioned together as separate entities in cameratoolbar.m)?

HG2 is still buggy, which explains why it is still not officially released. For example, the inspect(gca) function crashes Matlab, figure toolbars/menubars are missing, and some properties that are available in HG1 are missing in HG2. Also, we can add Java components to a Matlab figure using javacomponent as in HG1 (the returned container handles is a ui.HGJavaComponent class handle), but we get an error when we close the figure…
Still, with all this effort invested into HG2 I believe that it is only a matter of time before HG2 becomes officially released. This could happen perhaps even as soon as the upcoming R2010b release, but with the current state as seen above I suspect it will not happen before 2011. Also, my gut feeling is that Matlab will define any release that includes HG2 as a major release and we will finally have Matlab 8.0.
I would dearly love to hear any further information anyone discovers about HG2 and related issues. Please share your findings by email or in the comments section below.
Addendum Oct 3 2014: HG2 is finally released in Matlab release R2014b (8.4). It took more than 4 years after this article was posted for Mathworks to sort out all the problems in the new graphics engine. While HG2 is now fully supported, it contains numerous undocumented features and properties. I plan to discuss them in a separate upcoming series of articles.