Parameter Passing Protocol Description

As described in the previous section, most parameters and data are passed across the NuGraf Interface via functions whose arguments adhere to a variable-length parameter passing protocol. The protocol is based on a tagging scheme in which each data item or parameter is preceded by a keyword identifier, or token. Zero or more of these ‘token/data’ pairs are grouped together, in any order, to form the function’s argument list. When the function is called it pops off each ‘token/data’ pair from its argument stack and executes an appropriate parsing procedure that acts upon the data item. Tokens which are not recognized by a function’s parser are reported as syntax errors.

The ‘token’ is a predefined keyword identifier of datatype Nd_Token and ‘data’ is a pointer to any of the NuGraf-defined data types (all data is passed by reference across the interface). The tokens are predefined in the include file ‘ni.h’ and can be distinguished from other variables by their ‘Nt_’ letter prefix. See the ‘Abstract Data Types’ section for an explanation of the Nd_Token data type.

All data passed from the host application to the library is duplicated by the internal database manager in the library’s private data space, while data passed out of the library is directly copied by the database manager into the host application’s private data space (except for strings which are returned as pointers that point to the original string in the library’s private data space).

As a simple example of this protocol, the following command adds a new ‘point’ light source , with an intensity of 0.8 and located in space at location (10,20,10). The first column contains the keyword token, the second column is a pointer to a data item, and the third column terminates the ‘token/data’ pair.

example_code()
{
    Nd_Float	Nv_Light_Intensity = 0.8;
    Nd_Vector	Nv_Light_Shinefrom = { 10.0, 20.0, 10.0 };

    Ni_Light("light1",
        Nt_MODEL, Nt_POINT, Nt_CMDSEP,
        Nt_INTENSITY, &Nv_Light_Intensity, Nt_CMDSEP,
        Nt_SHINEFROM, Nv_Light_Shinefrom, Nt_CMDSEP,
        Nt_CMDEND);
}

‘token/data’ pairs are separated by the Nt_CMDSEP token and the argument list is terminated with the Nt_CMDEND token. It is crucial that the Nt_CMDEND token be included at the end of the list or else the program will likely crash (due to the parser reading off the end of the argument stack). Note that the Nt_CMDSEP token is optional if the argument list only contains a single ‘token/data’ pair. A ‘token/data’ pair (without the Nt_CMDSEP token) will be referred to as a clause.

In its simplest form the syntax for the parameter passing protocol is as follows:

Ni_Function_Name(
	token, data, Nt_CMDSEP,
	.
	.
	token, data, Nt_CMDSEP,
	Nt_CMDEND);

For example, the following code illustrates how to change the rendering level and screen resolution runtime options using a single call to the Ni_Option() function. The first line begins with the token Nt_RENDERLEVEL and is followed by the data item Nt_WIREFRAME, which in this case is yet another token (recall that a ‘data’ item can reference any NuGraf abstract data type). This will set the current rendering level mode for wireframe output. For the second clause, Nt_RESOLUTION is the token and the data item is a pointer to two 32-bit integers which define the new screen resolution.

example_code()
{
	Nd_Int        Nv_XY_Rez[] = { 640, 480 };

	Ni_Option(
		Nt_RENDERLEVEL, Nt_WIREFRAME, Nt_CMDSEP,
		Nt_RESOLUTION, (Nd_Int *) Nv_XY_Rez, Nt_CMDSEP,
		Nt_CMDEND);
}

Up to this point we have been stating that each clause is always specified in a ‘token/data’ format. In practice this is somewhat limiting since there are many cases where we would like to specify a number of different data items along with a single token. For example, the anti-aliasing option has an on/off flag (one data item) and its associated over-sampling values (another data item). To accommodate this requirement the interface allows for one or more sub-clauses to be associated with a main token.

The main clause begins with a token and is followed by one or more sub-clauses. Each sub-clause itself begins with a token and is followed by one or more data items. Unlike with the ‘token/data’ format, the Nt_CMDSEP token is placed after the last sub-clause, not after each sub-clause. Note that this extended format and the simpler ‘token/data’ format can both be accommodated within a function’s argument list (the ‘token/data’ format is actually just a simpler version of the extended format).

The following depicts the general syntax of the extended parameter passing protocol. The main clauses begin with ‘token’ and are followed by one or more sub-clauses each of which begins with ‘sub_token’.

Ni_Function_Name(
	token,
		sub_token, data, ... data,
		.
		.
		sub_token, data, ... data,
		Nt_CMDSEP,
	.
	.
	token,
		sub_token, data, ... data,
		.
		.
		sub_token, data, ... data,
		Nt_CMDSEP,
	Nt_CMDEND);

The following code illustrates the use of sub-clauses to modify the sub-options associated with the Nt_ANTIALIAS and Nt_SHOWNORMALS runtime options. The first main clause begins with Nt_ANTIALIAS and ends with Nt_CMDSEP, between which is listed two sub-clauses. The first sub-clause beginning with Nt_ENABLED turns the anti-aliasing mode on, and the Nt_OVERSAMPLE sub-clause specifies the over-sampling parameters.

The second main clause begins with Nt_SHOWNORMALS and ends with Nt_CMDSEP, between which is listed three sub-clauses. Nt_ENABLED turns the ‘show-normals’ option on, Nt_SCALE provides a scaling factor for the normals, and Nt_COLOR specifies that the normals should be red in color.

example_code()
{
	Nd_Int 	Nv_Oversampling_Values = { 1, 4 };
	Nd_Float 	Nv_Normal_Length = 0.5;

	Ni_Option(
		Nt_ANTIALIAS,
			Nt_ENABLED, Nt_ON,
			Nt_OVERSAMPLE, (Nd_Int *) Nv_Oversampling_Values,
			Nt_CMDSEP,
		Nt_SHOWNORMALS,
			Nt_ENABLED, Nt_ON,
			Nt_SCALE, (Nd_Float *) &Nv_Normal_Length,
			Nt_COLOR, Nt_COLORNAME, "red",
			Nt_CMDSEP,
		Nt_CMDEND);
}