DLL Non-Sequential User Defined Object data structure

  • 25 July 2022
  • 1 reply

For the User defined object DLL, Zemax passes a variable “data” to the function UserObjectDefinition. However, I have not been able to find any documentation on what each element of this array is. The examples provide some of the parameters (for example the CoatingSample.dll file gives the first 15 parameters and a few others up to parameter 34, see the code below from the example). Where can I find documentation to understand what other parameters I have access to from this data structure?


The data ZEMAX sends is formatted as follows:
        data[2], data[3], data[4] = x, y, z
        data[5], data[6], data[7] = l, m, n
        data[8] = coat group number
        data[9], data[10], data[11] = normal nx, ny, nz
        data[12], data[13] = current and next index of refraction
        data[14] = cosine of normal incidence angle
        data[15] = wavelength in µm
        data[20] =  zero flag. Set this to 1.0 to indicate the DLL
        computes the coating data, otherwise, ZEMAX will compute using
        object settings.

        for s polarization:
        data[21] = amplitude reflection real
        data[22] = amplitude reflection imaginary
        data[23] = amplitude transmission real
        data[24] = amplitude transmission imaginary
        for p polarization:
        data[31] = amplitude reflection real
        data[32] = amplitude reflection imaginary
        data[33] = amplitude transmission real
        data[34] = amplitude transmission imaginary


[Mod note: moved to more appropriate forum for DLL-related discussions.]


Best answer by Csilla Timar-Fulep 30 August 2022, 14:15

View original

1 reply

Userlevel 5
Badge +2


Thanks for your question here on the Community Forums!

You are correct, values are passed between OpticStudio and DLL with a data array, and this array contains all parameter data from the NSC editor and the ray data.

The DLL has two functions, as below:

  • UserParamNames(): returns parameter and face group names
  • UserObjectDefinition(): contains object definition

For the UserParamNames() function the data value passed to the DLL is as follows:

  • Data <= 0: OpticStudio wants name of particular face (i.e. -1 => face 1)
  • Data > 0: OpticStudio wants name of parameter names

On the other hand, for the UserObjectDefinition Function, the data would be the following:

  • Data[1] value indicates what the DLL should compute
    • Data[1] = 0
      • Place total number of triangular facets in Data[10]
      • Indicate if object is volume or shell in Data[11]
      • Indicate if object is diffractive in Data[12]
    • Data[1] = 1: list of triangles that compose tessellation
      • triangle info placed in tri_list array
    • Data[1] = 2: ray intercept and normal vector (after iteration)
      • OpticStudio provides ray coordinates and direction cosines on tessellation; DLL must iterate to exact surface
      • DLL returns path length to exact surface and normal vector at surface intercept point
    • Data[1] = 3: polarization data
    • Data[1] = 4: default/safe parameter values
  • Data[100] indicates the number of data parameters passed to the DLL
  •  Data[100+] are the values in parameter cells:
    •  Data[101] = parameter 1, Data[102] = parameter 2, etc.

You may find further information about NSC object DLLs in the Help system at:
The Setup Tab > Editors Group (Setup Tab) > Non-sequential Component Editor > Non-sequential Geometry Objects > User Defined Object

and in this knowledgebase article:
Custom DLLs in OpticStudio: An overview of user-defined surfaces, objects, and other DLL types – Knowledgebase (

For further references, I am attaching a pdf that provides more details about the individual data parameters.

Finally, I would also suggest to take a look at the sample codes EllipticalVolume and HalfCylinder in the \Documents\Zemax\DLL\Objects folder.