File: proposed-evnt-20020921.txt Changes to proposed-evnt-20020917: Fixed typos Changed 'see below' reference to a reference to the MNG specification This is proposed as a top-level MNG chunk that affects the overall handling of the MNG stream with respect to flow-control of segments based on user- interaction. It is proposed to add an "evNT" chunk, to propogate flow-control over the MNG based on external events. The chunk can appear at the MNG top level, but must not appear after a SAVE chunk. The appearance of 1 or more evNT chunks marks the MNG stream as a so-called 'dynamic' MNG. The evNT chunk contains 1 or more event-descriptors. Event-descriptors are matched by a decoder against events generated by the user-interface. At the moment only general mouse-pointer events are defined. These events should be accompanied by x/y-coordinates that indicate the position of the pointer relative to the top-left of the image canvas. So an x/y of 0/0 means the left-most,top-most pixel on the canvas; 25/10 means the pixel on the 11th row of the canvas 26 pixels from the left. The global evNT chunk contain 1 or more event-descriptors. An event- descriptor contains the following data: Event_type: 1 byte (unsigned integer) 0 = unknown event 1 = mouse enter 2 = mouse move 3 = mouse leave 4 = mouse key down 5 = mouse key up Mask_type: 1 byte (unsigned integer) 0 = no mask 1 = mask by frame 2 = mask by object 3 = mask by object using pixel-value 4 = mask by frame and object 5 = mask by frame and object using pixel-value Left: 4 bytes (signed integer) Must be omitted if the mask type is equal to 0, 2 or 3 Right: 4 bytes (signed integer) Must be omitted if the mask type is equal to 0, 2 or 3 Top: 4 bytes (signed integer) Must be omitted if the mask type is equal to 0, 2 or 3 Bottom: 4 bytes (signed integer) Must be omitted if the mask type is equal to 0, 2 or 3 Object_id: 2 bytes (unsigned integer) Must be omitted if the mask type is equal to 0 or 1 Index: 1 byte (unsigned integer) Must be omitted if the mask type is equal to 0, 1, 2 or 4 Segment_name: 1..79 bytes (Latin-1 string) If more than 1 event-descriptor is present in the chunk, they will be separated by a single null byte. There is no null byte separator after the last event-descriptor. If more than 1 evNT chunk is present the event-descriptors of subsequent chunks are added to the list of previously stored event-descriptors. The event type indicates the type of event this descriptor will be associated with. Multiple descriptors with the same event type may appear. A decoder must iterate through the descriptors in the order in which they appear within the MNG stream and within evNT chunks, until a match with a given event is found based on event type and a possible mask. It is not an error for descriptors to contain the same event type and overlapping masks. However the decoder must only honor the first matching descriptor. The mask type indicates if and what type of mask should be used to match a given event with this event-descriptor, but only if the event type has already matched: For mask type = 0 the event-descriptor matches. For mask type = 1 the event-descriptor matches if the x/y coordinates associated with the event lie within the rectangle given by the Left, Right, Top & Bottom parameters (Left and Top are inclusive, Right and Bottom are exclusive). For mask type = 2 the event-descriptor matches if the pixel of the stored object identified by the object id and indicated by the x/y coordinates associated with the event, contains a non-zero value. For mask type = 3 the event-descriptor matches if the pixel of the stored object identified by the object id and indicated by the x/y coordinates associated with the event, contains a value equal to the Index parameter. For mask type = 4 the event-descriptor matches if the x/y coordinates associated with the event lie within the rectangle given by the Left, Right, Top & Bottom parameters (Left and Top are inclusive, Right and Bottom are exclusive), and, if the pixel of the stored object identified by the object id and indicated by the x/y coordinates associated with the event minus the Left/Top parameters, contains a non-zero value. For mask type = 5 the event-descriptor matches if the x/y coordinates associated with the event lie within the rectangle given by the Left, Right, Top & Bottom parameters (Left and Top are inclusive, Right and Bottom are exclusive), and, if the pixel of the stored object identified by the object id and indicated by the x/y coordinates associated with the event minus the Left/Top parameters, contains a value equal to the Index parameter. The object id should match the object id of a stored object with a color type equal to 0 (grayscale) or 3 (indexed), and a bit depth of 8 or less. It is not an error if the object does not exist or doesn't have the proper color type or bit depth. However in this case the event-descriptor will never match. The stored object(s) must appear in the prologue segment prior to the SAVE chunk. The segment name indicates the SEEK chunk the decoder should locate and resume its flow when the event-descriptor matches a given event. It must follow the format of a tEXt keyword: It must consist only of printable Latin- 1 characters and must not have leading or trailing blanks, but can have single embedded blanks. There must be at least one and no more than 79 characters in the keyword. There is no null byte terminator within the segment name. There is a single null byte terminator after the segment name if the event-descriptor is followed by another event-descriptor. Segment names are case-sensitive. Use caution when printing or displaying keywords (Refer to Security considerations in the MNG specification, Chapter 17). It is an error if no SEEK chunk with the given segment name can be found. Decoders capable of handling the evNT chunk and events generated by the user- interface should treat a 'dynamic' MNG stream slightly different from a 'regular' stream. If 1 or more evNT chunks are encountered, the event- descriptors should be stored for later matching with user-interface generated events, and it must subsequently ignore segments other than the prologue segment and the first segment in the stream. When the user-interface triggers an event, the decoder must locate the first event-descriptor that matches the given event type and x/y coordinates. If found, the decoder should locate the SEEK chunk with a segment name equal to that in the event-descriptor and process the chunk and all subsequent chunks upto but not including the next SEEK chunk. For simplicity and to prevent machine lockups, a decoder may decide to ignore events when it is still processing a previous event or when it is still processing the prologue segment and the first segment. Decoders may ignore the TERM chunk when encountered inside a 'dynamic' MNG. Encoders should construct a 'dynamic' MNG stream that will appear normal when viewed by decoders that do not recognize the evNT chunk or do not handle events generated by the user-interface. The last segment in the stream should contain the 'regular' animation sequence or image.