The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SDL2-FFI-0.08
River stage zero No dependents
2 ++
/ SDL2::rect

NAME

SDL2::rect - SDL2::Rect Management Functions

SYNOPSIS

    use SDL2 qw[:rect];

DESCRIPTION

This package defines functions used to manage SDL2::Rect structures they may be imported by name of with the given tag.

Functions

These functions may be imported with the :rect tag.

SDL_PointInRect( ... )

Find out if a given point lies within a rectangle.

    my $dot  = SDL2::Point->new( { x => 100, y => 100 } );
    my $box1 = SDL2::Rect->new( { x => 0,  y => 0, w => 50,  h => 50 } );
    my $box2 = SDL2::Rect->new( { x => 50, y => 0, w => 100, h => 101 } );
    printf "point %dx%d is %sside of box 1\n", $dot->x, $dot->y,
        SDL_PointInRect( $dot, $box1 ) ? 'in' : 'out';
    printf "point %dx%d is %sside of box 2\n", $dot->x, $dot->y,
        SDL_PointInRect( $dot, $box2 ) ? 'in' : 'out';

Expected parameters include:

point - an SDL2::Point structure
rectangle - an SDL2::Rect structure

Returns true if point resides inside a rectangle.

SDL_RectEmpty( ... )

    my $box = SDL2::Rect->new( { w => 0, h => 100 } );
    printf 'box is %sempty', SDL_RectEmpty($box) ? '' : 'not ';

Expected parameters include:

rectangle - an SDL2::Rect structure to query

Returns true if the rectangle has no area.

SDL_RectEquals( ... )

Calculates whether or not two given rectangles are positionally and dimensionally the same.

    my $box1 = SDL2::Rect->new( { w => 0, h => 100, x => 5 } );
    my $box2 = SDL2::Rect->new( { w => 0, h => 100, x => 10 } );
    my $box3 = SDL2::Rect->new( { w => 0, h => 100, x => 10 } );
    printf "box 1 is %sthe same as box 2\n", SDL_RectEquals( $box1, $box2 ) ? '' : 'not ';
    printf "box 2 is %sthe same as box 3\n", SDL_RectEquals( $box2, $box3 ) ? '' : 'not ';
    printf "box 3 is %sthe same as box 1\n", SDL_RectEquals( $box3, $box1 ) ? '' : 'not ';

Expected parameters include:

lhs - first SDL2::Rect structure
rhs - second SDL2::Rect structure

Returns a true value if the two rectangles are equal.

SDL_HasIntersection( ... )

Determine whether two rectangles intersect.

    my $box1 = SDL2::Rect->new( { w => 10, h => 100, x => 5,   y => 10 } );
    my $box2 = SDL2::Rect->new( { w => 10, h => 100, x => 10,  y => 0 } );
    my $box3 = SDL2::Rect->new( { w => 10, h => 100, x => 100, y => 0 } );
    printf "box 1 %s box 2\n",
        SDL_HasIntersection( $box1, $box2 ) ? 'intersects' : 'does not intersect';
    printf "box 2 %s box 3\n",
        SDL_HasIntersection( $box2, $box3 ) ? 'intersects' : 'does not intersect';
    printf "box 3 %s box 1\n",
        SDL_HasIntersection( $box3, $box1 ) ? 'intersects' : 'does not intersect';

If either pointer is undef the function will return SDL_FALSE.

Expected parameters include:

lhs - an SDL2::Rect structure representing the first rectangle
rhs - an SDL2::Rect structure representing the second rectangle

Returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

SDL_IntersectRect( ... )

Calculate the intersection of two rectangles.

    my $box1 = SDL2::Rect->new( { w => 10, h => 100, x => 5,  y => 10 } );
    my $box2 = SDL2::Rect->new( { w => 10, h => 100, x => 10, y => 0 } );
    my $res  = SDL2::Rect->new();
    printf 'the intersection of boxes 1 and 2 looks like { x => %d, y => %d, w => %d, h => %d }',
        $res->x, $res->y, $res->w, $res->h
        if SDL_IntersectRect( $box1, $box2, $res );

If result is undef then this function will return SDL_FALSE.

Expected parameters include:

lhs - an SDL2::Rect structure representing the first rectangle
rhs - an SDL2::Rect structure representing the second rectangle
result an SDL2::Rect structure which will be filled in with the intersection of rectangles lhs and rhs

Returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

SDL_UnionRect( ... )

Calculate the union of two rectangles.

    my $box1 = SDL2::Rect->new( { w => 10, h => 100, x => 5,  y => 10 } );
    my $box2 = SDL2::Rect->new( { w => 10, h => 100, x => 10, y => 0 } );
    my $res  = SDL2::Rect->new();
    SDL_UnionRect( $box1, $box2, $res );
    printf 'the union of boxes 1 and 2 looks like { x => %d, y => %d, w => %d, h => %d }', $res->x,
        $res->y, $res->w, $res->h;

Expected parameters include:

lhs - an SDL2::Rect structure representing the first rectangle
rhs - an SDL2::Rect structure representing the second rectangle
result an SDL2::Rect structure which will be filled in with the intersection of rectangles lhs and rhs

SDL_EnclosePoints( ... )

Calculate a minimal rectangle enclosing a set of points.

    my $p1  = SDL2::Point->new( { x => 1, y => 10 } );
    my $p2  = SDL2::Point->new( { x => 5, y => 20 } );
    my $res = SDL2::Rect->new();
    printf 'points 1 and 2 are enclosed by a box like { x => %d, y => %d, w => %d, h => %d }',
        $res->x, $res->y, $res->w, $res->h
        if SDL_EnclosePoints( [ $p1, $p2 ], 2, undef, $res );

If clip is not undef then only points inside of the clipping rectangle are considered.

Expected parameters include:

points - an array of SDL2::Point structures representing points to be enclosed
count - the number of structures in the points array
clip - an SDL2::Rect used for clipping or undef to enclose all points
result - an SDL2::Rect structure filled in with the minimal enclosing rectangle

Returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the points were outside of the clipping rectangle.

SDL_IntersectRectAndLine( ... )

Calculate the intersection of a rectangle and line segment.

    my $box = SDL2::Rect->new( { x => 0, y => 0, w => 32, h => 32 } );
    my $x1  = 0;
    my $y1  = 0;
    my $x2  = 31;
    my $y2  = 31;
    printf 'line fully inside rect was clipped: %d,%d - %d,%d', $x1, $y1, $x2, $y2
        if SDL_IntersectRectAndLine( $box, \$x1, \$y1, \$x2, \$y2 );

This function is used to clip a line segment to a rectangle. A line segment contained entirely within the rectangle or that does not intersect will remain unchanged. A line segment that crosses the rectangle at either or both ends will be clipped to the boundary of the rectangle and the new coordinates saved in X1, Y1, X2, and/or Y2 as necessary.

Expected parameters include:

rect - an SDL2::Rect structure representing the rectangle to intersect
X1 - a pointer to the starting X-coordinate of the line
Y1 - a pointer to the starting Y-coordinate of the line
X2 - a pointer to the ending X-coordinate of the line
Y2 - a pointer to the ending Y-coordinate of the line

Returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>