formZ SDK | 4.0 Call Back Reference | Surface Style Representation
Description
Surface Style Representation preview function (Optional). This function is called
whenever a Surface Style 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. Note,
that this is only the case, if the FZ_SREP_FLAG_PREVIEW_NO_WINDEX flag
returned by the info callback is set to FALSE. Otherwise, the pview_windex
and fuim_data argument are the original project and srep data and it is
the srep's responsibilty to create a meaningful preview.
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_SREP_PVIEW_SIZE * FZ_SREP_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_srep_cbak_data_iface_pview(
fzrt_int | windex, |
fzrt_int | pview_windex, |
fzrt_int | action, |
dirty, | |
fuim_tmpl, | |
fuim_data, | |
unsigned char * | image_buffer, |
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 Surface Style Representation data.
image_buffer [Input]
The image buffer to be filled with the preview rendering. It is allocated by formZ and has exactly FZ_SREP_PVIEW_SIZE * FZ_SREP_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
6.0.0.2
Function Set
Defined in