- Undocumented Matlab - http://undocumentedmatlab.com -
Matlab’s HG2 mechanism
Posted By Yair Altman On May 7, 2010 @ 3:45 am In Handle graphics,Hidden property,High risk of breaking in future versions,Undocumented feature,Undocumented function | 13 Comments
A few days ago I posted  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  (UseHG2). In normal Matlab usage, this boolean property is ‘off’:
>> get(gcf,'usehg2') ans = off
HG2 is mentioned in quite a few Matlab files:
% 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  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):
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:
>> 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:
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.
Article printed from Undocumented Matlab: http://undocumentedmatlab.com
URL to article: http://undocumentedmatlab.com/blog/matlab-hg2
URLs in this post:
 Image: http://undocumentedmatlab.com/feed/
 email feed: http://undocumentedmatlab.com/subscribe_email.html
 posted: http://undocumentedmatlab.com/blog/undocumented-feature-function/
 hidden figure property: http://undocumentedmatlab.com/blog/displaying-hidden-handle-properties/
 discovered and reported: http://www.mathworks.com/matlabcentral/newsreader/view_thread/154510#387811
 New information on HG2 : http://undocumentedmatlab.com/blog/new-information-on-hg2
 Controlling plot data-tips : http://undocumentedmatlab.com/blog/controlling-plot-data-tips
 Draggable plot data-tips : http://undocumentedmatlab.com/blog/draggable-plot-data-tips
 Adding dynamic properties to graphic handles : http://undocumentedmatlab.com/blog/adding-dynamic-properties-to-graphic-handles
 Pinning annotations to graphs : http://undocumentedmatlab.com/blog/pinning-annotations-to-graphs
 HG2 update : http://undocumentedmatlab.com/blog/hg2-update
Copyright © Yair Altman - Undocumented Matlab. All rights reserved.