.\" Copyright (c) 2008-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. 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.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
.\"
.Dd December 21, 2022
.Dt AG_RECT 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Rect
.Nd agar rectangle structure
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
Many functions in Agar accept
.Fa AG_Rect
parameters.
This structure describes a two-dimensional integer rectangle:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_rect {
	int x, y;
	int w, h;
} AG_Rect;
.Ed
.Pp
Normalized rectangles have non-negative
.Fa w
and
.Fa h .
Rectangles are serialized using signed 16-bit coordinates, and
unsigned 16-bit sizes.
.\" MANLINK(AG_Rect2)
.Pp
The
.Ft AG_Rect2
variant includes a redundant endpoint (or alternatively, a redundant size
implied by the two endpoints).
This uses more space, but allows for faster intersection tests:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_rect2 {
	int x1, y1;
	int w, h;
	int x2, y2;
} AG_Rect2;
.Ed
.Sh INTERFACE
.nr nS 1
.Ft void
.Fn AG_RectInit "AG_Rect *rd" "int x" "int y" "int w" "int h"
.Pp
.Ft void
.Fn AG_Rect2Init "AG_Rect2 *rd" "int x" "int y" "int w" "int h"
.Pp
.Ft void
.Fn AG_ReadRect "AG_Rect *rd" "AG_DataSource *ds"
.Pp
.Ft void
.Fn AG_ReadRect2 "AG_Rect2 *rd" "AG_DataSource *ds"
.Pp
.Ft void
.Fn AG_WriteRect "AG_DataSource *ds" "const AG_Rect *r"
.Pp
.Ft void
.Fn AG_WriteRect2 "AG_DataSource *ds" "const AG_Rect2 *r"
.Pp
.Ft void
.Fn AG_Rect2ToRect "AG_Rect *rd" "AG_Rect2 r"
.Pp
.Ft void
.Fn AG_RectToRect2 "AG_Rect2 *rd" "AG_Rect *r"
.Pp
.Ft int
.Fn AG_RectIntersect "AG_Rect *rd" "const AG_Rect *a" "const AG_Rect *b"
.Pp
.Ft int
.Fn AG_RectIntersect2 "AG_Rect2 *rd" "const AG_Rect2 *a" "const AG_Rect2 *b"
.Pp
.Ft int
.Fn AG_RectInside "const AG_Rect *r" "int x" "int y"
.Pp
.Ft int
.Fn AG_RectInside2 "const AG_Rect2 *r" "int x" "int y"
.Pp
.Ft int
.Fn AG_RectCompare "const AG_Rect *a" "const AG_Rect *b"
.Pp
.Ft int
.Fn AG_RectCompare2 "const AG_Rect2 *a" "const AG_Rect2 *b"
.Pp
.Ft void
.Fn AG_RectSize "AG_Rect *r" "int w" "int h"
.Pp
.Ft void
.Fn AG_RectSize2 "AG_Rect2 *r" "int w" "int h"
.Pp
.Ft void
.Fn AG_RectTranslate "AG_Rect *r" "int x" "int y"
.Pp
.Ft void
.Fn AG_RectTranslate2 "AG_Rect2 *r" "int x" "int y"
.nr nS 0
.Pp
.Fn AG_RectInit
initializes an
.Ft AG_Rect
to coordinates
.Fa x ,
.Fa y
and dimensions
.Fa w ,
.Fa h .
.Pp
.Fn AG_Rect2Init
initializes an
.Ft AG_Rect2
to coordinates and dimensions and implicitely computes the endpoint
.Va x2 ,
.Va y2 .
.Pp
The
.Fn AG_ReadRect
function loads a rectangle from the given
.Xr AG_DataSource 3 .
.Fn AG_WriteRect
writes a rectangle to a data source.
.Pp
.Fn AG_RectToRect2
and
.Fn AG_Rect2ToRect
convert between the
.Ft AG_Rect
and
.Ft AG_Rect2
formats.
.Pp
.Fn AG_RectIntersect
and
.Fn AG_RectIntersect2
return intersection of rectangles
.Fa a
and
.Fa b .
.Pp
.Fn AG_RectInside
and
.Fn AG_RectInside2
return 1 if the point
.Fa x ,
.Fa y
lies inside of rectangle
.Fa r .
.Pp
.Fn AG_RectCompare
and
.Fn AG_RectCompare2
return 0 if both rectangles possess the same coordinates and dimensions.
.Pp
.Fn AG_RectSize
and
.Fn AG_RectSize2
resize a rectangle to the specified dimensions.
.Pp
.Fn AG_RectTranslate
and
.Fn AG_RectTranslate2
translate a rectangle by the specified amount.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3
.Sh HISTORY
The
.Nm
structure first appeared in Agar 1.3.4.