Documentation

Defining Input Size and Type

When you use Signal Processing Toolbox™ functions for code generation, you must define the size and type of the function inputs. One way to do this is with the -args compilation option. The size and type of inputs must be defined because C is a statically typed language. To illustrate the need to define input size and type, consider the simplest call to xcorr requiring two input arguments. The following demonstrates the differences in the use of xcorr in MATLAB^® and in Code Generation from MATLAB.

x = randn(512,1); %real valued white noise
y = randn(512,1); %real valued white noise
[C,lags] = xcorr(x,y);
x_circ = randn(256,1)+1j*randn(256,1); %circular white noise
y_circ = randn(256,1)+1j*randn(256,1); %circular white noise
[C1,lags1] = xcorr(x_circ,y_circ);

xcorr does not require the size and type of the input arguments. xcorr obtains this information at runtime. Contrast this behavior with a MEX-file created with codegen. Create the file myxcorr.m in a folder where you have read and write permission. Ensure that this folder is in the MATLAB search path. Copy and paste the following two lines of code into myxcorr.m and save the file. The compiler tag %#codegen must be included in the file.

function [C,Lags]=myxcorr(x,y)  %#codegen
[C,Lags]=xcorr(x,y);

Enter the following command at the MATLAB command prompt:

codegen myxcorr -args {zeros(512,1),zeros(512,1)} -o myxcorr 

Run the MEX-file:

x = randn(512,1); %real valued white noise
y = randn(512,1); %real valued white noise
[C,Lags] = myxcorr(x,y);

Define two new inputs x1 and y1 by transposing x and y.

x1 = x'; %x1 is 1x512
y1 = y'; %y1 is 1x512

Attempt to rerun the MEX-file with the transposed inputs.

[C,Lags] = myxcorr(x1,y1); %Errors

The preceding program errors with the message ??? MATLAB expression 'x' is not of the correct size: expected [512x1] found [1x512].

The error results because the inputs are specified to be 512x1 real-valued column vectors at compilation. For complex-valued inputs, you must specify that the input is complex valued. For example:

codegen myxcorr -o ComplexXcorr ...
-args {complex(zeros(512,1)),complex(zeros(512,1))}

Run the MEX-file at the MATLAB command prompt with complex-valued inputs of the correct size:

x_circ = randn(512,1)+1j*randn(512,1); %circular white noise
y_circ = randn(512,1)+1j*randn(512,1); %circular white noise
[C,Lags] = ComplexXcorr(x_circ,y_circ);

Attempting to run ComplexXcorr with real valued inputs results in the error: ??? MATLAB expression 'x' is not of the correct complexness.

Inputs must be Constants

For a number of supported Signal Processing Toolbox functions, the inputs or a subset of the inputs must be specified as constants at compilation time. Functions with this behavior are noted in the right column of the table List of Signal Processing Toolbox Functions that Support Code Generation. Use coder.Type with the -args compilation option, or enter the constants directly in the source code.

Specifying inputs as constants at compilation time results in significant advantages in the speed and efficiency of the generated code. For example, storing filter coefficients or window function values as vectors in the C source code improves performance by avoiding costly computation at runtime. Because a primary purpose of Code Generation from MATLAB is to generate optimized C code for desktop and embedded systems, emphasis is placed on providing the user with computational savings at runtime whenever possible.

To illustrate the constant input requirement with butter, create the file myLowpassFilter.m in a folder where you have read and write permission. Ensure that this folder is in the MATLAB search path. Copy and paste the following lines of code into myLowpassFilter.m and save the file.

function output = myLowpassFilter(input,N,Wn) %#codegen
[B,A] = butter(N,Wn,'low');
output = filter(B,A,input);

If you have the MATLAB Coder™ software, enter the following command at the MATLAB command prompt:

codegen myLowpassFilter -o myLowpassFilter ...
-args {zeros(512,1),coder.newtype('constant',5),coder.newtype('constant',0.1)} -report

Once the program compiles successfully, the following message appears in the command window: Code generation successful: View report.

Click on View report. Click on the C code tab on the top left and open the target source file myLowpassFilter.c.

Note that the numerator and denominator filter coefficients are included in the source code.

   static real_T dv0[6] = { 5.9795780369978346E-5, 0.00029897890184989173, ...
   static real_T dv1[6] = { 1.0, -3.9845431196123373, 6.4348670902758709, ...

Run the MEX-file without entering the constants:

output = myLowpassFilter(randn(512,1));

If you attempt to run the MEX-file by inputting the constants, you receive the error ??? Error using ==> myLowpassFilter 1 input required for entry-point 'myLowpassFilter'.

You may also enter the constants in the MATLAB source code directly. Edit the myLowPassFilter.m file and replace the MATLAB code with the lines:

function output = myLowpassFilter(input) %#codegen
[B,A] = butter(5,0.1,'low');
output = filter(B,A,input);

Enter the following command at the MATLAB command prompt:

codegen myLowpassFilter -args {zeros(512,1)} -o myLowpassFilter

Run the MEX-file by entering the following at the MATLAB command prompt:

output = myLowpassFilter(randn(512,1));