Difference between revisions of "Matlab Bindings"
(→define an appropriate binding subroutine in <tt>IXMclassname_m.f90</tt>) |
|||
Line 52: | Line 52: | ||
subroutine IXBplus_Testclass(nlhs, plhs, nrhs, prhs, status) | subroutine IXBplus_Testclass(nlhs, plhs, nrhs, prhs, status) | ||
</pre> | </pre> | ||
− | this provides access to the | + | this provides access to the <tt>IXBgetFromBinding</tt> interface to read the input objects from matlab, as well as any variable input arguments |
<pre> | <pre> | ||
use IXMm_testclass | use IXMm_testclass | ||
− | |||
implicit none | implicit none | ||
</pre> | </pre> |
Revision as of 15:15, 15 May 2008
The main binding to the Libisis framework which has been implemented is matlab. Each type defined in the framework has a module which contains type-specific methods for getting objects and variables from the matlab front-end and sending objects and variables back to the matlab front-end. These methods are called using two interfaces which are defined in a module IXMm_classname.
- IXBgetFromBinding
- IXBsendToBinding
This module is always defined in the file bindings/matlab/IXMclassname_m.f90. As a rule this module always contains the line use IXMclassname (it is however included automatically and does not need to be explicitly specified in the code)
The interfaces and methods of the IXMm_classname module are generated automatically using the preprocessor, in the following example for the IXTtestclass object in the IXMtestclass_m.f90 file. These are the only statements required to define the IXMm_testclass module.
module IXMm_testclass #define IXD_TYPE testclass #include "bindings_header.f90" contains #define IXD_TYPE testclass #include "bindings_base.f90" end module IXMm_testclass
If a class method implemented in the fortran framework is to be called from the matlab front-end various steps need to be followed.
define an appropriate binding subroutine in IXMclassname_m.f90
functions which are called from matlab are defined in the same file but outside of the IXMm_classname module. They are all prefixed with IXB. all the standard functions which are called such as IXBdisplay_classname, IXBcheck_classname are auto-generated using the preprocessor, so do not need any extra implementation.
#define IXD_TYPE testclass #include "bindings_extra.f90"
only functions which are extra to the standard module subroutines which you need to call from matlab have to have a binding subroutine defined. We can create an IXBplus_testclass subroutine to allow matlab calling of the IXFplus_testclass method of IXTtestclass.
The arguments of every IXBmethod_classname subroutine are the same
- nlhs is the number of left hand side arguments from matlab (ie what is the output of the matlab call)
- plhs(nlhs) is an array of pointers to the left hand side arguments
- nrhs is the number of right hand side arguments from matlab (ie what are the arguments of the matlab call)
- prhs(nrhs) is an array of pointers to the right hand side arguments
for the most part memory is shared between the matlab binding and fortran framework, so we work with pointers.
there are four types of subroutine which can be called, each with different variables which are returned to the matlab front-end
- functions which have no variable output eg. display,check (defined in bindings_base.f90)
- functions which return a simple type (real, integer, character string) eg. getting a value from an object
- functions which return an object(s) (IXTtestclass, IXTdataset_2d) eg. the result of a plus operation (defined below)
- functions which return an object(s) and a simple type back to matlab
subroutine IXBplus_Testclass(nlhs, plhs, nrhs, prhs, status)
this provides access to the IXBgetFromBinding interface to read the input objects from matlab, as well as any variable input arguments
use IXMm_testclass implicit none
standard declarations
integer :: nlhs, nrhs integer(cpointer_t) :: plhs(nlhs), prhs(nrhs)
declarations of input and output objects
type(IXTtestclass) :: wres, w1, w2 type(IXTstatus) :: status
- read in two structures which will be added together
- wres has been created empty with type statement,
- check read went OK - report errors and return if not
call IXBgetFromBinding(prhs(2),' ', 1, 0, w1, status) call IXBgetFromBinding(prhs(3),' ', 1, 0, w2, status) if (status == IXCseverity_error) return
do adding operation
call IXFplus_testclass(wres, w1, w2, status)
wres has now been filled and needs to be entered into the matlab memory if the process was successfull
if (status == IXCseverity_error) then plhs(1)=ixDuplicateArray(prhs(1)) else call IXBsendToBinding(plhs(1), prhs(1), ' ', 1, 0, wres, status) endif end subroutine
define object subroutine pair in libisisexc.txt
write an appropriate matlab function in bindings/matlab/classes/@IXTclassname directory
this function must make a call to the libisisexc DLL