001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.geometry.euclidean.twod;
018
019import java.util.List;
020
021/** Interface for objects that support linecast operations in Euclidean 2D space.
022 *
023 * <p>
024 * Linecasting is a process that takes a line or convex line subset and intersects it with
025 * the boundaries of a region. This is similar to
026 * <a href="https://en.wikipedia.org/wiki/Ray_casting">raycasting</a> used
027 * for collision detection with the exception that the intersecting element can be a
028 * line or convex line subset and not just a ray.
029 * </p>
030 */
031public interface Linecastable2D {
032
033    /** Intersect the given line against the boundaries in this instance, returning a
034     * list of all intersections in order of increasing position along the line. An empty
035     * list is returned if no intersections are discovered.
036     * @param line line the line to intersect
037     * @return a list of computed intersections in order of increasing position
038     *      along the line
039     */
040    default List<LinecastPoint2D> linecast(final Line line) {
041        return linecast(line.span());
042    }
043
044    /** Intersect the given line subset against the boundaries in this instance, returning
045     * a list of all intersections in order of increasing position along the line. An empty
046     * list is returned if no intersections are discovered.
047     * @param subset line subset to intersect
048     * @return a list of computed intersections in order of increasing position
049     *      along the line
050     */
051    List<LinecastPoint2D> linecast(LineConvexSubset subset);
052
053    /** Intersect the given line against the boundaries in this instance, returning
054     * the first intersection found when traveling in the direction of the line from
055     * infinity.
056     * @param line the line to intersect
057     * @return the first intersection found or null if no intersection
058     *      is found
059     */
060    default LinecastPoint2D linecastFirst(final Line line) {
061        return linecastFirst(line.span());
062    }
063
064    /** Intersect the given line subset against the boundaries in this instance, returning
065     * the first intersection found when traveling in the direction of the line subset
066     * from its start location.
067     * @param subset line subset to intersect
068     * @return the first intersection found or null if no intersection
069     *      is found
070     */
071    LinecastPoint2D linecastFirst(LineConvexSubset subset);
072}