formZ SDK | 4.0 Call Back Reference | Light Representation

# fz_light_rep_cbak_data_iface_pview_func

Description

Light Representation preview function (Optional). This function is called whenever a Light is edited. It is expected to create the preview rendering that show the surface style rendered on a sample object. The preview scene is defined as a separate formZ project, whose index is passed in as the pview_windex parameter. All project settings are defined in such a way, that the plugin can render the scene using the view, surface styles, images size ... of that project.
The action argument tells the preview function, when it is called. A value of 0 indicates, that it is called when the dialog is first opened by the user. It gives the plugin the opportunity to initialize any data necessary for the preview. It is not expected to generate a rendering at that time. A value of 1 indicates, that a new preview rendering is needed. It is called as often with that value as the user makes changes. A value of 2 indicates that the user closed the dialog. The plugin may now finalize any data. No rendering is expected at that time.
The preview function should call the api fz_rmtl_iface_pview_update as frequently as possible to allow the user to see the progress of the preview rendering in the dialog. A good interval would be, for example, once every scanline. The fz_rmtl_iface_pview_update api expects the preview rendering to be defined as an rgb pixel buffer of FZ_LIGHT_REP_PVIEW_SIZE * FZ_LIGHT_REP_PVIEW_SIZE * 3 bytes. This buffer is allocated by formZ and passed to the preview function.
The preview function should also call the api fz_rmtl_iface_pview_interrupt frequently. If this api returns TRUE, the preview rendering needs to be interrupted and the preview function must return FALSE for the complete argument. For example, the user may have selected an dialog item while the rendering is executing. In order to do this, the rendering needs to stop, controll needs to be returned to the dialog driver, which will handle the user's click. If the user changed a setting, the preview function will be called again with TRUE for the dirty argument, meaning ,that a new image needs to be started. If the user did not make any changes, the preview function will be called with FALSE for the dirty argument. The preview function may then continue the rendering, where it was previously interrupted. If a preview rendering is completed, the complete argument must be returned as TRUE. Again, it is important, that interrupting is handled properly and in a responsive manner to allow the user to interact with the dialog while the rendering is proceeding.
If this function is not implemented, formZ will display the default preview rendering, that is also shown in the Simple tab.

Plugin Prototype

fzrt_error_td fz_light_rep_cbak_data_iface_pview_func(

fzrt_int | windex,
fzrt_int | pview_windex,
fzrt_int | action,
fzrt_boolean | dirty,
fz_fuim_tmpl_ptr | fuim_tmpl,
fzrt_ptr | fuim_data,
unsigned char * | image_buffer,
fzrt_boolean * | complete )

Parameters

windex [Input]

origin project window index

pview_windex [Input]

index of the project window containing the preview scene

action [Input]

identifies, when the preview function is called. 0 : it is called at the beginning. when the dialog is first opened. It is called only once with this value. 1 : it is called to generate a new preview rendering. it is called as often as the user makes changes inthe dialog. 2 : it is called at the end, when the dialog is closed. It is called only once with this value.

dirty [Input]

TRUE, if a brand new preview image is required, FALSE, if a previously cancelled rendering may be continued.

fuim_tmpl [Input]

Pointer to the dialog template.

fuim_data [Input]

Pointer to the Light Representation data.

image_buffer [Input]

The image buffer to be filled with the preview rendering. It is allocated by formZ and has exactly FZ_LIGHT_REP_PVIEW_SIZE * FZ_LIGHT_REP_PVIEW_SIZE * 3 bytes.

complete [Result]

Return TRUE, if the preview image was completed sucessfully. Return FALSE if the preview rendering was interrupted before completion.

Returns

Error codes

Availability

7.0.0.0

Function Set

Defined in

fz_view_rep_api.h