Info Catalog octave: Mex-Files octave: Working with Matrices and Arrays in Mex-Files

octave: Getting Started with Mex-Files

 
 A.2.1 Getting Started with Mex-Files
 ------------------------------------
 
 The basic command to build a mex-file is either ‘mkoctfile --mex’ or
 ‘mex’.  The first command can be used either from within Octave or from
 the command line.  To avoid issues with MATLAB’s own ‘mex’ command, the
 use of the command ‘mex’ is limited to within Octave.  Compiled
 mex-files have the extension ‘.mex’.
 
  -- : mex [options] file ...
      Compile source code written in C, C++, or Fortran, to a MEX file.
 
      This is equivalent to ‘mkoctfile --mex [options] file’.
 
      See also: mkoctfile XREFmkoctfile, mexext XREFmexext.
 
  -- : mexext ()
      Return the filename extension used for MEX files.
 
      See also: mex XREFmex.
 
    Consider the following short example:
 
      #include "mex.h"
      
      void
      mexFunction (int nlhs, mxArray *plhs[],
                   int nrhs, const mxArray *prhs[])
      {
        mexPrintf ("Hello, World!\n");
      
        mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);
      }
 
    The first line ‘#include "mex.h"’ makes available all of the
 definitions necessary for a mex-file.  One important difference between
 Octave and MATLAB is that the header file "matrix.h" is implicitly
 included through the inclusion of "mex.h".  This is necessary to avoid a
 conflict with the Octave file "Matrix.h" for operating systems and
 compilers that don’t distinguish between filenames in upper and lower
 case.
 
    The entry point into the mex-file is defined by ‘mexFunction’.  The
 function takes four arguments:
 
   1. The number of return arguments (# of left-hand side args).
 
   2. An array of pointers to return arguments.
 
   3. The number of input arguments (# of right-hand side args).
 
   4. An array of pointers to input arguments.
 
    Note that the function name definition is not explicitly included in
 ‘mexFunction’ and so there can only be a single ‘mexFunction’ entry
 point per file.  Instead, the name of the function as seen in Octave is
 determined by the name of the mex-file itself minus the extension.  If
 the above function is in the file ‘myhello.c’, it can be compiled with
 
      mkoctfile --mex myhello.c
 
 which creates a file ‘myhello.mex’.  The function can then be run from
 Octave as
 
      myhello (1,2,3)
      ⇒ Hello, World!
      ⇒ I have 3 inputs and 0 outputs
 
    It should be noted that the mex-file contains no help string.  To
 document mex-files, there should exist an m-file in the same directory
 as the mex-file itself.  Taking the above as an example, there would
 need to be a file ‘myhello.m’ which might contain the text
 
      %MYHELLO Simple test of the functionality of a mex-file.
 
    In this case, the function that will be executed within Octave will
 be given by the mex-file, while the help string will come from the
 m-file.  This can also be useful to allow a sample implementation of the
 mex-file within the Octave language itself for testing purposes.
 
    Although there cannot be multiple entry points in a single mex-file,
 one can use the ‘mexFunctionName’ function to determine what name the
 mex-file was called with.  This can be used to alter the behavior of the
 mex-file based on the function name.  For example, if
 
      #include "mex.h"
      
      void
      mexFunction (int nlhs, mxArray *plhs[],
                   int nrhs, const mxArray *prhs[])
      {
        const char *nm;
      
        nm = mexFunctionName ();
        mexPrintf ("You called function: %s\n", nm);
        if (strcmp (nm, "myfunc") == 0)
          mexPrintf ("This is the principal function\n", nm);
      
        return;
      }
 
 is in the file ‘myfunc.c’, and is compiled with
 
      mkoctfile --mex myfunc.c
      ln -s myfunc.mex myfunc2.mex
 
 then as can be seen by
 
      myfunc ()
      ⇒ You called function: myfunc
          This is the principal function
      myfunc2 ()
      ⇒ You called function: myfunc2
 
 the behavior of the mex-file can be altered depending on the function’s
 name.
 
    Although the user should only include ‘mex.h’ in their code, Octave
 declares additional functions, typedefs, etc., available to the user to
 write mex-files in the headers ‘mexproto.h’ and ‘mxarray.h’.
 

Info Catalog octave: Mex-Files octave: Working with Matrices and Arrays in Mex-Files