Loc.pbj

/*  CBR
 *  Loc.pbj
 *
 *  Copyright (c) 2009, Ewen Cheslack-Postava
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of Sirikata nor the names of its contributors may
 *    be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

"pbj-0.0.3"

import "TimedMotionVector.pbj";
import "TimedMotionQuaternion.pbj";
import "AggregateBoundingInfo.pbj";

package Sirikata.Protocol.Loc;

message LocationUpdate {
    required uuid object = 1;

    // The seqno is used to indicate relative age of updates so out of order
    // updates can be handled properly. They aren't guaranteed to be sequential
    // (i.e. you might receive 4, 7, 19), but they are guaranteed to be
    // monotonically increasing. However, sequence numbers are also only valid
    // between proximity additions/removals.  It is possible they will be reset
    // when objects are removed and then added back again.
    // Not that while the ordering within a BulkLocationUpdate and a sequence
    // number there would be sufficient for the client to properly handle out of
    // order updates, it is provided in LocationUpdates individually to make
    // the client code simpler, at the expense of slightly larger packets.
    optional uint64 seqno = 6;

    // Epochs are related to seqno, but allow a the requester of
    // updates to tell whether a request has been handled. Updates are
    // sent with an epoch number and this value is reported in
    // LocationUpdates (only back to the objects itself, since its the
    // only one that needs to resolve differences between requests and
    // updates). By comparing the value in the update to its latest
    // request, the client can decide which value to use.
    optional uint64 epoch = 8;

    optional Sirikata.Protocol.TimedMotionVector location = 2;
    optional Sirikata.Protocol.TimedMotionQuaternion orientation = 3;

    // This is the old version of bounds where we just used a bounding
    // sphere. It is removed, but maintained in comments to avoid a conflicting
    // field #
    // optional boundingsphere3f bounds = 4;
    // This is the version you should now use, which encodes offset,
    // bounds of center points, and maximum object size.
    optional Sirikata.Protocol.AggregateBoundingInfo aggregate_bounds = 10;

    optional string mesh = 5;
    optional bytes physics = 7;
    optional bytes query_data = 12;

    // The parent object. Do not specify if you don't perform or expose
    // aggregates, or if this object is the root node.
    optional uuid parent = 9;


    // List of identifiers of indices this update is relevant to. Servers
    // may be using the object in multiple indexes (trees), e.g. for
    // rebuilding, and therefore the client will need to apply this update
    // to multiple trees. Since Loc updates can arrive before their
    // corresponding prox additions ("orphan" updates) we need to provide
    // this information in the message rather than relying on the client
    // to keep track of it (otherwise the client wouldn't know that it
    // actually has an orphan update for one of the indices and end up with
    // out of date state that may never get fixed).
    //
    // Modes without index/tree replication will not use this field.
    repeated uint32 index_id = 11;

    // current max id = 12
}

message BulkLocationUpdate {
    repeated LocationUpdate update = 1;
}


// Payload for request from an object to space to update its location.
// This should be sent from object -> Space(Loc) in an
// ObjectMessage.
message LocationUpdateRequest {
    optional Sirikata.Protocol.TimedMotionVector location = 1;
    optional Sirikata.Protocol.TimedMotionQuaternion orientation = 2;
    optional boundingsphere3f bounds = 3;
    optional string mesh = 4;
    optional bytes physics = 5;
    optional bytes query_data = 7;

    // See note in LocationUpdate about how to use epochs.
    optional uint64 epoch = 6;
}

message Container {
    optional LocationUpdateRequest update_request = 1;
}