ANY-maze Help > The ANY-maze reference > ANY-maze plug-ins > Plug-in API reference > AME_POSN message

AME_POSN message

The processing of this message is time-critical. See Remarks section for details.

The AME_POSN message is sent to a plug-in during a test. One message is sent to each active plug-in for each detected position of the animal.

Parameters

guid

Pointer to the GUID of the plug-in which is being notified of the position. All plug-ins that the user has activated (in the protocol) will be sent this message (except for any plug-in which returned AME_ERROR from its AME_TESTSTART processing.)

If a DLL only implements a single plug-in, it can ignore this parameter - although it is good practice to always check it.

wParam

Size of the AME_POSNDATA record pointed to by lParam, in bytes.

lParam

Pointer to an AME_POSNDATA record. See Remarks section for details.

Return value

The only valid return codes from this message are:

•

AME_OK

•

AME_ERROR

If the message is processed successfully, then return AME_OK.

If an error occurs, return AME_ERROR. Note that your plug-in will continue to receive AME_POSN messages during the rest of the test, and will also receive an AME_TESTEND or AME_TESTABORT message at the end of the test. Therefore, if an error occurs which means the results of your analysis are no longer valid, you should flag this in your context record and simply return immediately (with a return value of AME_ERROR) on all subsequent AME_POSN messages. At the test end, you should return AME_CANCELLED to force any results that you returned prior to the error to be deleted.

Remarks

The AME_POSNDATA record includes a Context field. This points at the context value you returned during AME_TESTSTART processing.

If your analysis returns a result, you should write the result value to the ResultValue field of the AME_POSNDATA record and the result type to the ResultType field. Here the ResultType should agree with the result type you return from AME_GETRESULTTYPE messages.

If your plug-in does not return a result, then you should set the ResultType field to RT_NONE and return AME_OK.

The processing of this message is time critical. ANY-maze can perform simultaneous analysis of up to 40 video images, and can be receiving images at 30 frames per second. Thus, in an extreme case, it may be required to analyse 1200 frames per second. This gives under a millisecond for each frame. Realistically, in this case, ANY-maze will probably start to drop frames and only actually process 15 frames per second from each image. Nevertheless, there's little time for the analysis of each frame, so you should try to ensure that the analysis you perform is as fast as possible. Of course, you may know that no one will use your plug-in with more than (for example) 2 pieces of apparatus, and therefore ANY-maze will need to analyse, at most, 60 frames per second, giving 16ms per frame; or you may choose to specify that your analysis should only be used on a single piece of apparatus, thus giving you time to perform complex analysis. However, whatever limits may apply, you should always bear in mind that the analysis performed by a plug-in occurs in real-time and should be as efficient as possible.

ANY-maze help topic T1018