External Interfaces/API

Passing Two or More Inputs or Outputs

The plhs[] and prhs[] parameters are vectors that contain pointers to each left-hand side (output) variable and each right-hand side (input) variable, respectively. Accordingly, plhs[0] contains a pointer to the first left-hand side argument, plhs[1] contains a pointer to the second left-hand side argument, and so on. Likewise, prhs[0] contains a pointer to the first right-hand side argument, prhs[1] points to the second, and so on.

This example, xtimesy, multiplies an input scalar by an input scalar or matrix and outputs a matrix. For example, using xtimesy with two scalars gives

• x = 7;
  y = 7;
  z = xtimesy(x,y)
  
  z = 
       49
  

Using xtimesy with a scalar and a matrix gives

• x = 9;
  y = ones(3);
  z = xtimesy(x,y)
  
  z = 
       9      9      9
       9      9      9
       9      9      9
  

This is the corresponding MEX-file C code.

• /*
   * =============================================================
   * xtimesy.c - example found in API guide
   *
   * Multiplies an input scalar times an input matrix and outputs a
   * matrix. 
   *
   * This is a MEX-file for MATLAB.
   * Copyright (c) 1984-2000 The MathWorks, Inc.
   * =============================================================
   */
  
  /* $Revision: 1.9 $ */
  
  #include "mex.h"
  
  void xtimesy(double x, double *y, double *z, int m, int n)
  {
    int i,j,count = 0;
    
    for (i = 0; i < n; i++) {
      for (j = 0; j < m; j++) {
        *(z+count) = x * *(y+count);
        count++;
      }
    }
  }
  
  
  /* The gateway routine */
  void mexFunction(int nlhs, mxArray *plhs[],
                   int nrhs, const mxArray *prhs[])
  {
    double *y, *z;
    double x;
    int status,mrows,ncols;
    
    /*  Check for proper number of arguments. */
    /* NOTE: You do not need an else statement when using
       mexErrMsgTxt within an if statement. It will never
       get to the else statement if mexErrMsgTxt is executed.
       (mexErrMsgTxt breaks you out of the MEX-file.) 
    */
    if (nrhs != 2) 
      mexErrMsgTxt("Two inputs required.");
    if (nlhs != 1) 
      mexErrMsgTxt("One output required.");
    
    /* Check to make sure the first input argument is a scalar. */
    if (!mxIsDouble(prhs[0]) || mxIsComplex(prhs[0]) ||
        mxGetN(prhs[0])*mxGetM(prhs[0]) != 1) {
      mexErrMsgTxt("Input x must be a scalar.");
    }
    
    /* Get the scalar input x. */
    x = mxGetScalar(prhs[0]);
    
    /* Create a pointer to the input matrix y. */
    y = mxGetPr(prhs[1]);
    
    /* Get the dimensions of the matrix input y. */
    mrows = mxGetM(prhs[1]);
    ncols = mxGetN(prhs[1]);
    
    /* Set the output pointer to the output matrix. */
    plhs[0] = mxCreateDoubleMatrix(mrows,ncols, mxREAL);
    
    /* Create a C pointer to a copy of the output matrix. */
    z = mxGetPr(plhs[0]);
    
    /* Call the C subroutine. */
    xtimesy(x,y,z,mrows,ncols);
  }
  

As this example shows, creating MEX-file gateways that handle multiple inputs and outputs is straightforward. All you need to do is keep track of which indices of the vectors prhs and plhs correspond to the input and output arguments of your function. In the example above, the input variable x corresponds to prhs[0] and the input variable y to prhs[1].

Note that mxGetScalar returns the value of x rather than a pointer to x. This is just an alternative way of handling scalars. You could treat x as a 1-by-1 matrix and use mxGetPr to return a pointer to x.

Passing Strings

Passing Structures and Cell Arrays