4. Report Writing - ProRender,LogFile

The modules ProRender and LogFile are designed to facilitate the generation of text and graphics content for report writing. Note that these modules are under preliminary development and the functions and argument lists are subject to change.

Table of Contents

4.1 Rendering - ProRender

The ProRender module is designed to generate graphics objects and render them to 2D image files and 3D object files. The methods associated with a ProRender object are the following.

Begin and end an instance of an object, generic object functions

*vfx_ProRenderBegin    - create an instance of a ProRender object
vfx_ProRenderEnd       - destroy an instance of a ProRender object
vfx_ProRenderError     - return ProRender object error flag

Operations

vfx_ProRenderDraw      - render to image file
vfx_ProRenderFile      - export to object file
vfx_ProRenderModel     - generate graphics object of Model
vfx_ProRenderState     - generate graphics object of State
vfx_ProRenderSetDimension - set image pixel dimensions
vfx_ProRenderSetLookAt - set viewing transformation
vfx_ProRenderSetObject - set attribute objects
vfx_ProRenderSetParamc - set character parameters
vfx_ProRenderSetParami - set integer parameters

Instance a ProRender object using vfx_ProRenderBegin. Use vfx_ProRenderSetObject to register the current Model object. This gives ProRender access to the model element connectivity and node coordinate information. The complete process of creating a 2D image file or 3D object file is a two step process. First an internal graphics object is generated of either a finite element model or result using vfx_ProRenderModel or vfx_ProRenderState respectively. Then this internal graphics object may be drawn to a 2D image file (such as a GIF file) using vfx_ProRenderDraw or exported to a 3D object file (such as a VRML file) using vfx_ProRenderFile.

When rendering to an image file (currently only GIF is supported). The dimension of the final image in pixels is set using vfx_ProRenderSetDimension. The viewing transformation used is set using vfx_ProRenderSetLookAt. Use the function vfx_ProRenderSetParamc to set the output file name. The image file name should include the extension .gif, the object file name should include the extension .wrl.

Destroy an instance of a ProRender object using vfx_ProRenderEnd.

Table of Contents

4.2 Function Descriptions

The currently available ProRender functions are described in detail in this section.

Table of Contents , ProRender

NAME

*vfx_ProRenderBegin - create an instance of a ProRender object

C SPECIFICATION

vfx_ProRender *vfx_ProRenderBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created ProRender object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a ProRender object. Memory is allocated for the object private data and the pointer to the object is returned.

Destroy an instance of a ProRender object using

     void vfx_ProRenderEnd (vfx_ProRender *prorender)

Return the current value of a ProRender object error flag using

     Vint vfx_ProRenderError (vfx_ProRender *prorender)

Table of Contents , ProRender

NAME

vfx_ProRenderDraw - render to image file

C SPECIFICATION

void vfx_ProRenderDraw (vfx_ProRender *prorender)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Render a previously generated object to a GIF file.

Table of Contents , ProRender

NAME

vfx_ProRenderFile - export to object file

C SPECIFICATION

void vfx_ProRenderFile (vfx_ProRender *prorender)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Export a previously generated object to a VRML file.

Table of Contents , ProRender

NAME

vfx_ProRenderModel - generate graphics object of Model

C SPECIFICATION

void vfx_ProRenderModel (vfx_ProRender *prorender)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Generate a graphics object of the current Model attribute object. The model is rendered in gray with feature edges added.

Table of Contents , ProRender

NAME

vfx_ProRenderState - generate graphics object of State

C SPECIFICATION

void vfx_ProRenderState (vfx_ProRender *prorender)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Generate a graphics object of the current State attribute object. A contour plot of a scalar derived quantity is generated. The vector magnitude is used for vector states, Von Mises stress is used for tensor states and the translation magnitude is used for six dof states.

Table of Contents , ProRender

NAME

vfx_ProRenderSetDimension - set image pixel dimensions

C SPECIFICATION

void vfx_ProRenderSetDimension (vfx_ProRender *prorender,
                                Vint xsize,
                                Vint ysize)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.
xsize        Horizontal dimension in pixels
ysize        Vertical dimension in pixels

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the pixel dimension of generated image. The default is xsize = 320 and ysize = 240.

Table of Contents , ProRender

NAME

vfx_ProRenderSetLookAt - set viewing transformation

C SPECIFICATION

void vfx_ProRenderSetLookAt (vfx_ProRender *prorender,
                             Vfloat ex, Vfloat ey, Vfloat ez, 
                             Vfloat cx, Vfloat cy, Vfloat cz, 
                             Vfloat ux, Vfloat uy, Vfloat uz)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.
ex,ey,ez     Position of eye
cx,cy,cz     Point along line of sight
ux,uy,uz     Vector pointing in up direction

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the viewing transformation used to render image. The default eye position is (1.,0.,0.), point along line of sight is (0.,0.,0.) and up direction is (0.,1.,0.).

Table of Contents , ProRender

NAME

vfx_ProRenderSetObject - set attribute objects

C SPECIFICATION

void vfx_ProRenderSetObject (vfx_ProRender *prorender,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.
objecttype   The object type identifier
             =VIS_MODEL              Model object
             =VIS_STATE              State object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The Model object must be registered. The State object must be registered if vfx_ProRenderState is executed.

Table of Contents , ProRender

NAME

vfx_ProRenderSetParamc - set character parameters

C SPECIFICATION

void vfx_ProRenderSetParamc (vfx_ProRender *prorender,
                             Vint ptype,
                             Vchar *cparam)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.
ptype        Type of solution parameter to set
             =PRORENDER_OUTFILE      Pathname for output file
cparam       Specifies the character value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify character parameters to control output file name. By default the output file is prorender.gif.

Table of Contents , ProRender

NAME

vfx_ProRenderSetParami - set integer parameters

C SPECIFICATION

void vfx_ProRenderSetParami (vfx_ProRender *prorender,
                             Vint ptype,
                             Vint iparam)

INPUT ARGUMENTS

prorender    Pointer to ProRender object.
ptype        Type of solution parameter to set
             =PRORENDER_EDGECOLOR     Edge color
             =PRORENDER_FACECOLOR     Face color
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify integer parameters to control entity color, etc. The edge and face colors must be chosen from the set of available colors in the vis_ColorMapRamp function when using the COLORMAP_SET ramp. By default edge color is COLORMAP_SET_WHITE and face color is COLORMAP_SET_GRAY50.

Table of Contents

4.3 Log File Content - LogFile

The LogFile module is designed to generate text content for monitoring the progress of a finite element solution. The methods associated with a LogFile object are the following.

Begin and end an instance of an object, generic object functions

*vfx_LogFileBegin      - create an instance of a LogFile object
vfx_LogFileEnd         - destroy an instance of a LogFile object
vfx_LogFileError       - return LogFile object error flag

Operations

vfx_LogFileSetError    - set error handler to use with LogFile
vfx_LogFileSetObject   - set attribute objects

Output

vfx_LogFileTableInit   - flag beginning of a table
vfx_LogFileTableTerm   - flag end of a table
vfx_LogFileTableEntryc - create table entry with string
vfx_LogFileTableEntryd - create table entry with double
vfx_LogFileTableEntryi - create table entry with integer
vfx_LogFileTableEntry1 - create one typed table entry
vfx_LogFileTableEntry2 - create two typed table entry
vfx_LogFileTableEntry3 - create three typed table entry
vfx_LogFileTableEntry4 - create four typed table entry
vfx_LogFileTableEntry5 - create five typed table entry
vfx_LogFileTextString  - write unformatted string

Instance a LogFile object using vfx_LogFileBegin. Use vfx_LogFileSetObject to register the TextFun object where output will be written to. Use vfx_LogFileSetError to use the internally-defined error handler so all solver output is integrated with the TextFun object registered. Send messages and/or tables to the log file using vfx_LogFileTextString and/or any of the table entry function variations.

Destroy an instance of a LogFile object using vfx_LogFileEnd.

Table of Contents

4.4 Function Descriptions

The currently available LogFile functions are described in detail in this section.

Table of Contents , LogFile

NAME

*vfx_LogFileBegin - create an instance of a LogFile object

C SPECIFICATION

vfx_LogFile *vfx_LogFileBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created LogFile object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a LogFile object. Memory is allocated for the object private data and the pointer to the object is returned.

Destroy an instance of a LogFile object using

     void vfx_LogFileEnd (vfx_LogFile *logfile)

Return the current value of a LogFile object error flag using

     Vint vfx_LogFileError (vfx_LogFile *logfile)

Table of Contents , LogFile

NAME

vfx_LogFileSetObject - set attribute objects

C SPECIFICATION

void vfx_LogFileSetObject (vfx_LogFile *logfile,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.
objecttype   The object type identifier
             =VSY_TEXTFUN              TextFun object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The TextFun object must be registered.

Table of Contents , LogFile

NAME

vfx_LogFileSetError - set error handler to use with LogFile

C SPECIFICATION

void vfx_LogFileSetError (vfx_LogFile *logfile)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the error handler to a LogFile specific function which will stream error messages through LogFile. This function will replace the currently defined error handler and error object. Please see vut_ErrorSetHandler and vut_ErrorSetObject.

Table of Contents , LogFile

NAME

vfx_LogFileTableInit - flag beginning of a table

C SPECIFICATION

void vfx_LogFileTableInit (vfx_LogFile *logfile,
                           const Vchar *message)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.
message      Table title

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OPERATION is generated if vfx_LogFileTableInit has already been called without a corresponding vfx_LogFileTableTerm call to indicate the end of the table.

DESCRIPTION

Flag the beginning of a new table.

Table of Contents , LogFile

NAME

vfx_LogFileTableTerm - flag end of a table

C SPECIFICATION

void vfx_LogFileTableTerm (vfx_LogFile *logfile)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OPERATION is generated if vfx_LogFileTableInit has not been called.

DESCRIPTION

Flag the end of a table.

Table of Contents , LogFile

NAME

vfx_LogFileTableEntryc - create table entry with string

C SPECIFICATION

void vfx_LogFileTableEntryc (vfx_LogFile *logfile,
                             const Vchar *message,
                             const Vchar *cvalue)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.
message      Descriptive string
cvalue       Value corresponding to descriptive string

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OPERATION is generated if vfx_LogFileTableInit has not been called.

DESCRIPTION

Adds a line to the table of the form

     --------------------
     | message | cvalue |
     --------------------

Create similar lines in the table with a double or an integer parameter using

     void vfx_LogFileTableEntryd (vfx_LogFile *logfile,
                                  const Vchar *message,
                                  Vdouble dvalue)
     void vfx_LogFileTableEntryi (vfx_LogFile *logfile,
                                  const Vchar *message,
                                  Vint ivalue)

Table of Contents , LogFile

NAME

vfx_LogFileTableEntry1 - create one typed table entry

C SPECIFICATION

void vfx_LogFileTableEntry1 (vfx_LogFile *logfile,
                             Vint type1,
                             Vobject *value1)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.
type1        Type of value
             =LOGFILE_STRING         Null-terminated string
             =LOGFILE_SPACE          A null-terminated string of spaces
             =LOGFILE_IMAGE          File name with image
             =LOGFILE_INTEGER        An integer value
             =LOGFILE_DOUBLE         A double value
             =LOGFILE_FLOAT          A float value
value1       Object with value data

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OPERATION is generated if vfx_LogFileTableInit has not been called. SYS_ERROR_ENUM is generated if type1 is not a valid entry.

DESCRIPTION

Adds a line to the table of the form

     ----------
     | value1 |
     ----------

If type1 is set to LOGFILE_STRING then value1 is a null-terminated string; if type1 is set to LOGFILE_INTEGER, LOGFILE_DOUBLE, or LOGFILE_FLOAT, then value1 is the address of the integer, double, or float, respectively. If type1 is set to LOGFILE_SPACE then LogFile will ensure that the number of spaces is respected, incluing in HTML files.

If type1 is set to LOGFILE_IMAGE and the underlying TextFun object supports the display of images (.e.g, HTMLText), then the image will be displayed. Otherwise, the file name is displayed.

Create similar lines in the table with 2 to 5 column entries using

     void vfx_LogFileTableEntry2 (vfx_LogFile *logfile,
                                  Vint type1,
                                  Vobject *value1,
                                  Vint type1,
                                  Vobject *value2)

     -------------------
     | value1 | value2 |
     -------------------

     void vfx_LogFileTableEntry3 (vfx_LogFile *logfile,
                                  Vint type1,
                                  Vobject *value1,
                                  Vint type1,
                                  Vobject *value2,
                                  Vint type3,
                                  Vobject *value3)

     ----------------------------
     | value1 | value2 | value3 |
     ----------------------------

     void vfx_LogFileTableEntry4 (vfx_LogFile *logfile,
                                  Vint type1,
                                  Vobject *value1,
                                  Vint type1,
                                  Vobject *value2,
                                  Vint type3,
                                  Vobject *value3,
                                  Vint type4,
                                  Vobject *value4)

     -------------------------------------
     | value1 | value2 | value3 | value4 |
     -------------------------------------

     void vfx_LogFileTableEntry5 (vfx_LogFile *logfile,
                                  Vint type1,
                                  Vobject *value1,
                                  Vint type1,
                                  Vobject *value2,
                                  Vint type3,
                                  Vobject *value3,
                                  Vint type4,
                                  Vobject *value4,
                                  Vint type5,
                                  Vobject *value5)

     ----------------------------------------------
     | value1 | value2 | value3 | value4 | value5 |
     ----------------------------------------------

Table of Contents , LogFile

NAME

vfx_LogFileTextString - write unformatted string

C SPECIFICATION

void vfx_LogFileTextString (vfx_LogFile *logfile,
                            const Vchar *message)

INPUT ARGUMENTS

logfile      Pointer to LogFile object.
message      String to be displayed

OUTPUT ARGUMENTS

None

ERRORS

None.

DESCRIPTION

Sends the string to the log file.