## Documentation Center |

The code generation software attempts to generate code for functions,
even if they are not supported for C code generation. The software
detects calls to many common visualization functions, such as `plot`, `disp`,
and `figure`. The software treats these functions
like extrinsic functions but you do not have to declare them extrinsic
using `coder.extrinsic`. During simulation, the
code generation software generates code for these functions, but does
not generate their internal code. During standalone code generation, MATLAB^{®} attempts
to determine whether the visualization function affects the output
of the function in which it is called. Provided that the output does
not change, MATLAB proceeds with code generation, but excludes
the visualization function from the generated code. Otherwise, compilation
errors occur.

For example, you might want to call `plot` to
visualize your results in the MATLAB environment. If you generate
a MEX function from a function that calls `plot` and
then run the generated MEX function, the code generation software
dispatches calls to the `plot` function to MATLAB.
If you generate a library or executable, the generated code does not
contain calls to the `plot` function. The code
generation report highlights calls from your MATLAB code to extrinsic
functions so that it is easy to determine which functions are supported
only in the MATLAB environment.

For unsupported functions other than common visualization functions,
you must declare the functions (like `pause`) to
be extrinsic (see Resolution of Function Calls for Code Generation). Extrinsic functions
are not compiled, but instead executed in MATLAB during simulation
(see How MATLAB Resolves Extrinsic Functions During Simulation).

There are two ways to declare a function to be extrinsic:

Use the

`coder.extrinsic`construct in main functions or local functions (see Declaring MATLAB Functions as Extrinsic Functions).Call the function indirectly using

`feval`(see Calling MATLAB Functions Using feval).

To declare a MATLAB function to be extrinsic, add the `coder.extrinsic` construct
at the top of the main function or a local function:

coder.extrinsic('function_name_1', ... , 'function_name_n');

The following code declares the MATLAB `patch` function extrinsic in the local
function `create_plot`:

function c = pythagoras(a,b,color) %#codegen % Calculates the hypotenuse of a right triangle % and displays the triangle. c = sqrt(a^2 + b^2); create_plot(a, b, color); function create_plot(a, b, color) %Declare patch and axis as extrinsiccoder.extrinsic('patch');x = [0;a;a]; y = [0;0;b]; patch(x, y, color); axis('equal');

The code generation software detects that `axis` is
not supported for code generation and automatically treats it as an
extrinsic function. The compiler does not generate code for `patch` and `axis`,
but instead dispatches them to MATLAB for execution.

To test the function, follow these steps:

Convert

`pythagoras`to a MEX function by executing this command at the MATLAB prompt:codegen -report pythagoras -args {1, 1, [.3 .3 .3]}

Click the link to the code generation report and then, in the report, view the MATLAB code for

`create_plot`.The report highlights the

`patch`and`axis`functions to indicate that they are supported only within the MATLAB environment.Run the MEX function by executing this command:

pythagoras_mex(3, 4, [1.0 0.0 0.0]);

MATLAB displays a plot of the right triangle as a red patch object:

Use the `coder.extrinsic` construct to:

Call MATLAB functions that do not produce output — such as

`pause`— during simulation, without generating unnecessary code (see How MATLAB Resolves Extrinsic Functions During Simulation).Make your code self-documenting and easier to debug. You can scan the source code for

`coder.extrinsic`statements to isolate calls to MATLAB functions, which can potentially create and propagate`mxArrays`(see Working with mxArrays).Save typing. With one

`coder.extrinsic`statement, each subsequent function call is extrinsic, as long as the call and the statement are in the same scope (see Scope of Extrinsic Function Declarations).Declare the MATLAB function(s) extrinsic throughout the calling function scope (see Scope of Extrinsic Function Declarations). To narrow the scope, use

`feval`(see Calling MATLAB Functions Using feval).

Observe the following rules when declaring functions extrinsic for code generation:

Declare the function extrinsic before you call it.

Do not use the extrinsic declaration in conditional statements.

The `coder.extrinsic` construct has function
scope. For example, consider the following code:

function y = foo %#codegen coder.extrinsic('rat','min'); [N D] = rat(pi); y = 0; y = min(N, D);

In this example, `rat` and `min` as
treated as extrinsic every time they are called in the main function `foo`.
There are two ways to narrow the scope of an extrinsic declaration
inside the main function:

Declare the MATLAB function extrinsic in a local function, as in this example:

function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = 0; y = mymin(N, D); function y = mymin(a,b) coder.extrinsic('min'); y = min(a,b);

Here, the function

`rat`is extrinsic every time it is called inside the main function`foo`, but the function`min`is extrinsic only when called inside the local function`mymin`.Call the MATLAB function using

`feval`, as described in Calling MATLAB Functions Using feval.

The function `feval` is
automatically interpreted as an extrinsic function during code generation.
Therefore, you can use `feval` to conveniently
call functions that you want to execute in the MATLAB environment,
rather than compiled to generated code.

Consider the following example:

function y = foo coder.extrinsic('rat'); [N D] = rat(pi); y = 0; y = feval('min', N, D);

Because `feval` is extrinsic, the statement `feval('min',
N, D)` is evaluated by MATLAB — not compiled
— which has the same result as declaring the function `min` extrinsic
for just this one call. By contrast, the function `rat` is
extrinsic throughout the function `foo`.

MATLAB resolves calls to extrinsic functions — functions that do not support code generation — as follows:

During simulation, MATLAB generates code for the call to an extrinsic function, but does not generate the function's internal code. Therefore, you can run the simulation only on platforms where you install MATLAB software.

During code generation, MATLAB attempts to determine
whether the extrinsic function affects the output of the function
in which it is called — for example by returning `mxArrays` to
an output variable (see Working with mxArrays). Provided that the output does
not change, MATLAB proceeds with code generation, but excludes
the extrinsic function from the generated code. Otherwise, MATLAB issues
a compiler error.

The output of an extrinsic function is an `mxArray` —
also called a MATLAB array. The only valid operations for `mxArrays` are:

Storing

`mxArrays`in variablesPassing

`mxArrays`to functions and returning them from functionsConverting

`mxArrays`to known types at run time

To use `mxArrays` returned by extrinsic functions
in other operations, you must first convert them to known types, as
described in Converting mxArrays to Known Types.

To convert an `mxArray` to a known type, assign
the `mxArray` to a variable whose type is defined.
At run time, the `mxArray` is converted to the type
of the variable assigned to it. However, if the data in the `mxArray` is
not consistent with the type of the variable, you get a run-time error.

For example, consider this code:

function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = min(N, D);

Here, the top-level function `foo` calls
the extrinsic MATLAB function `rat`, which
returns two `mxArrays` representing the numerator `N` and
denominator `D` of the rational fraction approximation
of `pi`. Although you can pass these `mxArrays` to
another MATLAB function — in this case, `min` —
you cannot assign the `mxArray` returned by `min` to
the output `y`.

If you run this function `foo` in a MATLAB Function
block in a Simulink^{®} model, the code generates the following error
during simulation:

Function output 'y' cannot be of MATLAB type.

To fix this problem, define `y` to be the type
and size of the value that you expect `min` to return
— in this case, a scalar double — as follows:

function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = 0; % Define y as a scalar of type double y = min(N,D);

The full MATLAB run-time environment is not supported during code generation. Therefore, the following restrictions apply when calling MATLAB functions extrinsically:

MATLAB functions that inspect the caller, or read or write to the caller's workspace do not work during code generation. Such functions include:

The MATLAB debugger cannot inspect variables defined in extrinsic functions.

Functions in generated code may produce unpredictable results if your extrinsic function performs the following actions at run time:

Change folders

Change the MATLAB path

Delete or add MATLAB files

Change warning states

Change MATLAB preferences

Change Simulink parameters

Was this topic helpful?