Dynamic Echo
OpenVX virtual forms are designed to easily handle dynamic
echoing. This allows you to provided useful graphical clues to the user
during the data collection phase of their function.
The sample function to project points of a polygon to a specified
plane provides a good example of how this is done. The source code for
this function is in the file: openvx/src/ovxPolyArea.c.
First, in your data collection template, you need to specify
a function that will manage your echo. This is done by specifying a function
with the "echo=" keyword in the template header. For
Example:
|
TEMPLATE=OpenVxPolyArea description=Measure area and perimeter of polygon function=ovxPolyArea echo=PolyAreaEcho
... |
The parameter list for the function you call must be of the
form shown below.
|
void PolyAreaEcho ( VsObjHandle *oh_data, /* i: pointer to form's data object handle */ VsObjHandle *oh_echo /* i: pointer to form's echo object handle*/ ) /* |
DESCRIPTION:
Echo projected polygon and associated data.
There is not a return value.
|
*/ { ... return; } |
In order for your function to echo input data, you will need
to know the index of the data collection object. This is passed into the
echo routine in "oh_data->index", oh_data is the first
parameter.
In the function PolyAreaEcho() you will note that
we have the line:
|
"idx_in = oh_data->index;" |
Then we use idx_in the same way we do the first parameter
from our function ovxPolyArea().
The functions VxEchoBeg() and VxEchoEnd() have
been provided to init your echo environment and restore your old environment
respectively. VxEchoBeg returns two integers which must me stored
and passed back to VxEchoEnd to restore things to normal. These
should be the first and last thing that you do in your echo routine.
You may notice a check for a NULL input from *oh_data. When
you are done collecting input, the echo function is called one last time
with this NULL input to allow you to do any need cleanup. For the example
function this extra call is just ignored.
|
int fTrans, idBin;
/* Start of executable code */
/* Init echo variables. */ VxEchoBeg(&idBin, &fTrans); if (oh_data == V_NULL) goto F_END; ...
F_END:;
/* Restore original environment. */ VxEchoEnd(idBin, fTrans); |
The function CdEchoDraw() may be used to display your
echoed objects. If you are just creating a single object, you may pass
in the object handle to that object. If you need to echo several objects
then you may create a "Block" object and add your entities to
the block, (use CdObjAddTo() to do this) then finally call CdEchoDraw()
with the object handle of the block. The latter method is the one shown
in the example since several line segments were to be shown with each
echo.
The function CdEchoDel() is used to delete the previous echo, which you must do before calling CdEchoDraw() again. CdEchoDel() has an unfortunate side-effect that it changes the active bin. The active bin must be the project bin for echo to work as designed (VxEchoBeg() sets this for you). So inside of your code you must follow this call with a call to VxEchoBinReset(PRJ_BIN).
