diff options
Diffstat (limited to 'navit/route.c')
| -rw-r--r-- | navit/route.c | 49 |
1 files changed, 37 insertions, 12 deletions
diff --git a/navit/route.c b/navit/route.c index e367c3855..c67455902 100644 --- a/navit/route.c +++ b/navit/route.c @@ -94,7 +94,9 @@ struct route_graph_point { * least costs */ struct fibheap_el *el; /**< When this point is put on a Fibonacci heap, this is a pointer * to this point's heap-element */ - int value; /**< The cost at which one can reach the destination from this point on */ + int value; /**< The cost at which one can reach the destination from this point on. + * {@code INT_MAX} indicates that the destination is unreachable from this + * point, or that this point has not yet been examined. */ struct coord c; /**< Coordinates of this point */ int flags; /**< Flags for this point (eg traffic distortion) */ }; @@ -112,7 +114,7 @@ struct route_graph_point { struct route_segment_data { struct item item; /**< The item (e.g. street) that this segment represents. */ int flags; - int len; /**< Length of this segment */ + int len; /**< Length of this segment, in meters */ /*NOTE: After a segment, various fields may follow, depending on what flags are set. Order of fields: 1.) maxspeed Maximum allowed speed on this segment. Present if AF_SPEED_LIMIT is set. 2.) offset If the item is segmented (i.e. represented by more than one segment), this @@ -215,7 +217,8 @@ struct route_info { /** * @brief A complete route path * - * This structure describes a whole routing path + * A route path is an ordered set of segments describing the route from the current position (or previous + * destination) to the next destination. */ struct route_path { int in_use; /**< The path is in use and can not be updated */ @@ -247,8 +250,8 @@ struct route { struct route_graph *graph; /**< Pointer to the route graph */ struct route_path *path2; /**< Pointer to the route path */ - struct map *map; - struct map *graph_map; + struct map *map; /**< The map containing the route path */ + struct map *graph_map; /**< The map containing the route graph */ struct callback * route_graph_done_cb ; /**< Callback when route graph is done */ struct callback * route_graph_flood_done_cb ; /**< Callback when route graph flooding is done */ struct callback_list *cbl2; /**< Callback list to call when route changes */ @@ -263,7 +266,8 @@ struct route { /** * @brief A complete route graph * - * This structure describes a whole routing graph + * The route graph holds all routable segments along with the connections between them and the cost of + * each segment. */ struct route_graph { int busy; /**< The graph is being built */ @@ -1165,8 +1169,9 @@ route_clear_destinations(struct route *this_) * and updates the route. * * @param this The route to set the destination for - * @param dst Coordinates to set as destination - * @param count Number of destinations (last one is final) + * @param dst Points to an array of coordinates to set as destinations, which will be visited in the + * order in which they appear in the array (the last one is the final destination) + * @param count Number of items in {@code dst}, 0 to clear all destinations * @param async If set, do routing asynchronously */ @@ -2150,6 +2155,15 @@ route_value_seg(struct vehicleprofile *profile, struct route_graph_point *from, return ret; } +/** + * @brief Whether two route graph segments match. + * + * Two segments match if both start and end at the exact same points. Other points are not considered. + * + * @param s1 The first segment + * @param s2 The second segment + * @return true if both segments match, false if not + */ static int route_graph_segment_match(struct route_graph_segment *s1, struct route_graph_segment *s2) { @@ -2162,11 +2176,13 @@ route_graph_segment_match(struct route_graph_segment *s1, struct route_graph_seg /** * @brief Sets or clears a traffic distortion for a segment. * - * This sets or clears a delay. It cannot be used to set speed. + * This sets a delay (setting speed is not supported) or clears an existing traffic distortion. + * Note that, although setting a speed is not supported, calling this function with a delay of 0 + * will also clear an existing speed constraint. * * @param this The route graph * @param seg The segment to which the traffic distortion applies - * @param delay Delay in tenths of a second + * @param delay Delay in tenths of a second, or 0 to clear an existing traffic distortion */ static void route_graph_set_traffic_distortion(struct route_graph *this, struct route_graph_segment *seg, int delay) @@ -2199,10 +2215,10 @@ route_graph_set_traffic_distortion(struct route_graph *this, struct route_graph_ } /** - * @brief Adds a route distortion item to the route graph + * @brief Adds a traffic distortion item to the route graph * * @param this The route graph to add to - * @param item The item to add + * @param item The item to add, must be of {@code type_traffic_distortion} */ static void route_process_traffic_distortion(struct route_graph *this, struct item *item) @@ -2932,6 +2948,15 @@ route_graph_process_restrictions(struct route_graph *this) } } +/** + * @brief Releases all resources needed to build the route graph. + * + * If {@code cancel} is false, this function will start processing restrictions and ultimately call + * the route graph's {@code done_cb} callback. + * + * @param rg Points to the route graph + * @param cancel True if the process was aborted before completing, false if it completed normally + */ static void route_graph_build_done(struct route_graph *rg, int cancel) { |