|  | VISION Documentation (LDV) |  | Last update: 17/09/00
Download documentation | 7. R E C O M M E N D A T I O N S |

Even if managing and programming LDVs is simple, it must respect some common sense rules, one cannot simply do whatever he wants! Here are some rules and clarification on some points which might be troubling when one programs his first LDVs:

# | Recommendations / Advises
1 | If you write an LDV, send it to me! I would like VISION site to centralise all the LDVs created. Verify also that your LDV is not compiled with debug information! It would be to no use, except reduce the performances!
2 | It would be nice and useful for everyone to give the sources of the LDV with the LDV itself... This could give some good ideas to some people...
3 | Do not forget that, by the means of the functions called by VISION, you have a direct access to VISION internal memory. Thus, if you act a little randomly with the pointers provided, VISION will most likely crash sooner or later...
4 | If you use VAPI (recommended!), the same remark applies, the global Vapi variable of the LDV points directly on VISION memory. If you write into this structure, your LDV might crash! I let you imagine the consequences if you modify the address of the function PrSetProg and then try and call it!

5

The ERROR to avoid in the function Run is to allocate yourself the memory for the image passed in the out parameter. Why? Doing this, first, you overwrite the pointer VISION has already allocated to that. Furthermore, as soon as VISION will try to use it, it will crash. If fact, your LDV is more or less "a PRG" launched by VISION and terminated when VISION (more excactly the LDG manager) decides it. At this moment, the compiler or the system will free the memory allocated by this module, even if you do not do it explicitely. That is why that is always VISION, using the function PreRun that will allocate the memory for the LDV, since it will use it after that. The function PreRun is really essential!

6

If you use the function PrSetProg from VAPI (really WARMLY recommended, unless your LDV is fast as light!), try not to call it too often, for instance inside a loop, it has no use (it may happen that the percentage has not even changed!) and this will slow unecesseraly your LDV. Before your call, put a test such as if ( ( iter & 0x0F ) == x0F ), it will call the progress function only one out of sixteen times, this should be largely enough.

7 | The function PrSetProg from VAPI, gives control temporarily to the AES. This will allow to move windows at that moment. That is also one of the reasons why this function must be called a little... but not too much!
8 | If your LDV has parameters (at most 4 parameters), you must use an associated INI file. I recommend to associate systematically an INI file to your LDV. It's really handy for translations, and not difficult at all!
9 | If you use an INI file, your LDV must control the validity of passed parameters, and not crash stupidely if one of them is out of bounds... In such a case, just return the ELDV_INVALIDPARAMETER error code. Do not forget that the INI file is a text file, which can be easily modified by a user...

10

Floating numbers, while forecasted for a future exxtension, are not necessary for LDV parameters. Let's say you must enter a value between 0.0 and 1.0. All you have to do is to indicate a range of [0;1000] in the INI file (which still gives you more precision that what can be entered in the GUI), to convert the parameter given by VISION to float, and then to divide it by 1000. There must exist weird cases where floats are necessary, but one should do without them in 99% of the cases!

11 | I advise, for memory performances reasons, to allways use LDVF_OPINPLACE and LDVF_SPECFORMAT flags. Allocate the memory you want in the LDV (if you can...) and free it after its execution.
12 | If you work only on lines and columns, use the LDVF_SPECFORMAT flag. The VDI function vr_cpyfm is made for that purpose. Using the LDVF_ATARIFORMAT or LDVF_STDFORMAT flags would oblige VISION to allocate memory unecessarily (furthermore, the VDI functions ALWAYS work on the machine specific format: LDVF_SPECFORMAT!)

13

If you have to handle TOS and/or VDI indexes:

- You can work by lines or packets of n lines:
  Use the format LDVF_SPECFORMAT, and the functions of the Raster interface. This will minimise the memory to allocate
- You are obliged to have access to any index at any time:
  Use the format LDVF_ATARIFORMAT, and the functions of the Raster interface. VISION will convert the image from the specific format to the ATARI bitplan format before calling PreRun or Run.

14

Even if the user has selected a block as an area to apply the LDV on the image, you are not limited to the area defined by this block. You have access to the whole image, even more if you decide to enlarge its size (fields out->fd_w and out->fd_h of the function <a But do not forget to update the fields x1, x2, y1 and y2 of the structure LDV_PARAMS given by the function PreRun, and also to UNDO buffer, to be able to go back.

15 |
16 |

|  | VISION Documentation (LDV) |  | Last update: 17/09/00
Download documentation | 7. R E C O M M E N D A T I O N S |