%%================================================
%% S3d help source file
%% 08/AUG/2013
%% 
%% * Run make.au3 to convert this file into HTML.
%% Not completed yet!
%%================================================

%% a single line comment...

%%================================================
%% Global section

%title
S3d Function Reference

%before
S3d - Simple 3D Graphic Library
{{{
- v1.2.3 (16/AUG/2013)
- Tested on: Windows XP SP3
              AutoIt v3.3.8.1, v3.3.9.17
- Requires GDIPlus.au3
}}}

Below is a complete list of the user defined functions available in S3d.

When using them you need to add a #include <S3d.au3>.

* This reference has yet to be completed.

%after
Author: Starg

%%================================================
%section
_S3d_SelectGraphic

%desc
Selects a Graphics object to work with

%syntax
_S3d_SelectGraphic($hGraphic, $iWidth, $iHeight, [$iSmooth = 2])

%param
$hGraphic = Graphics object to work with
$iWidth = Width in pixels
$iHeight = Height in pixels
%% "*" will be replaced with "(Optinal)"
$iSmooth = *Smoothing mode

%%================================================
%section
_S3d_SelectPen

%desc
Selects a pen object to work with

%syntax
_S3d_SelectPen($hPen)

%param
$hPen = Pen object to work with

%%================================================
%section
_S3d_SelectBrush

%desc
Selects a brush object to work with

%syntax
_S3d_SelectBrush($hBrush)

%param
$hPen = Brush object to work with

%%================================================
%section
_S3d_SelectFont

%desc
Selects a font object to work with

%syntax
_S3d_SelectFont($hFont)

%param
$hFont = Font object to work with

%%================================================
%section
_S3d_SelectFormat

%desc
Selects a String Format object to work with

%syntax
_S3d_SelectFormat($hFormat)

%param
$hFormat = String Format object to work with

%%================================================
%section
_S3d_Dist

%desc
Calculates the distance between two points

%syntax
_S3d_Dist([$nPos1X = 0 [, $nPos1Y = 0 [, $nPos1Z = 0 [, $nPos2X = 0 [, $nPos2Y = 0 [, $nPos2Z = 0 ]]]]]])

%param
$nPos1X = *The X coordinate of the point 1
$nPos1Y = *The Y coordinate of the point 1
$nPos1Z = *The Z coordinate of the point 2
$nPos2X = *The X coordinate of the point 2
$nPos2Y = *The Y coordinate of the point 2
$nPos2Z = *The Z coordinate of the point 2

%return
Calculated distance betwenn two points

%%================================================
%section
_S3d_DistFromCamera

%desc
Calculates the distance between the camera and a specified point

%syntax
_S3d_DistFromCamera([$nPosX = 0 [, $nPosY = 0 [, $nPosZ = 0 ]]])

%param
$nPosX = *The X coordinate of a specified point
$nPosY = *The Y coordinate of a specified point
$nPosZ = *The Z coordinate of a specified point

%return
Calculated distance betwenn the camera and a specified point

%%================================================
%section
_S3d_SetCamera

%desc
Moves the camera

%syntax
_S3d_SetCamera($nCameraX, $nCameraY, $nCameraZ, $nTargetX, $nTargetY, $nTargetZ, [$nVAngle = 0 [, $nFAngle = 0.8 [, $nFScale = 1000 ]]])

%param
$nCameraX = The X coordinate of the camera
$nCameraY = The Y coordinate of the camera
$nCameraZ = The Z coordinate of the camera
$nTargetX = The X coordinate of the point that the camera looks at
$nTargetY = The Y coordinate of the point that the camera looks at
$nTargetZ = The Z coordinate of the point that the camera looks at
$nVAngle = *The angle between the camera top and the screen top
$nFAngle = *The view angle
$nFScale = *The base scale value (global)

%related
_S3d_SetCameraEx

%%================================================
%section
_S3d_SetCameraEx

%desc
Moves the camera

%syntax
_S3d_SetCameraEx($nCameraX, $nCameraY, $nCameraZ, [$nXYAngle = 0 [, $nXZAngle = 0 [, $nVAngle = 0 [, $nFAngle = 0.8 [, $nFScale = 1000 ]]]]])

%param
$nCameraX = The X coordinate of the camera
$nCameraY = The Y coordinate of the camera
$nCameraZ = The Z coordinate of the camera
$nXYAngle = *The camera angle (horizontal)
$nXZAngle = *The camera angle (vertical)
$nVAngle = *The angle between the camera top and the screen top
$nFAngle = *The view angle
$nFScale = *The base scale value (global)

%related
_S3d_SetCamera

%%================================================
%section
_S3d_SetLocalMatrix

%desc
Defines local coordinates

%syntax
_S3d_SetLocalMatrix([$n00 = 1 [, $n01 = 0 [, $n02 = 0 [, $n03 = 0 [, $n10 = 0 [, $n11 = 1 [, $n12 = 0 [, $n13 = 0 [, $n20 = 0 [, $n21 = 0 [, $n22 = 1 [, $n23 = 0 [, $n30 = 0 [, $n31 = 0 [, $n32 = 0 [, $n33 = 1]]]]]]]]]]]]]]]])

%param
$n00 - $n33 = *New values for the Local Matrix

%remarks
If all the parameters are omitted, Local Matrix will be an identity matrix.

%related
_S3d_MultiplyLocalMatrix
_S3d_LocalTranslate
_S3d_LocalScale
_S3d_LocalRotateX
_S3d_LocalRotateY
_S3d_LocalRotateZ
_S3d_SetLocalMatrixEx

%%================================================
%section
_S3d_MultiplyLocalMatrix

%desc
Modifies local coordinates

%syntax
_S3d_MultiplyLocalMatrix([$n00 = 1 [, $n01 = 0 [, $n02 = 0 [, $n03 = 0 [, $n10 = 0 [, $n11 = 1 [, $n12 = 0 [, $n13 = 0 [, $n20 = 0 [, $n21 = 0 [, $n22 = 1 [, $n23 = 0 [, $n30 = 0 [, $n31 = 0 [, $n32 = 0 [, $n33 = 1]]]]]]]]]]]]]]]])

%param
$n00 - $n33 = *Values for a matrix that the Local Matrix is multiplied  by

%related
_S3d_SetLocalMatrix
_S3d_LocalTranslate
_S3d_LocalScale
_S3d_LocalRotateX
_S3d_LocalRotateY
_S3d_LocalRotateZ

%%================================================
%section
_S3d_LocalTranslate

%desc
Translates the local coordinates

%syntax
_S3d_LocalTranslate($nX, $nY, $nZ)

%param
$nX, $nY, $nZ = The amount of a translation

%related
_S3d_MultiplyLocalMatrix

%%================================================
%section
_S3d_LocalScale

%desc
Scales the local coordinates

%syntax
_S3d_LocalScale($nX, $nY, $nZ)

%param
$nX, $nY, $nZ = Scale values

%related
_S3d_MultiplyLocalMatrix

%%================================================
%section
_S3d_LocalRotateX

%desc
Rotates the local coordinates along the X axis

%syntax
_S3d_LocalRotateX($nAngle [, $fDeg = False])

%param
$nAngle = The angle of rotation along the X axis
$fDeg = *Degree flag, see remarks

%remarks
$nAngle is radians if $fDeg is false, degrees if true.

%related
_S3d_LocalRotateY
_S3d_LocalRotateZ

%%================================================
%section
_S3d_LocalRotateY

%desc
Rotates the local coordinates along the Y axis

%syntax
_S3d_LocalRotateY($nAngle [, $fDeg = False])

%param
$nAngle = The angle of rotation along the Y axis
$fDeg = *Degree flag, see remarks

%remarks
$nAngle is radians if $fDeg is false, degrees if true.

%related
_S3d_LocalRotateX
_S3d_LocalRotateZ

%%================================================
%section
_S3d_LocalRotateZ

%desc
Rotates the local coordinates along the Z axis

%syntax
_S3d_LocalRotateZ($nAngle [, $fDeg = False])

%param
$nAngle = The angle of rotation along the Z axis
$fDeg = *Degree flag, see remarks

%remarks
$nAngle is radians if $fDeg is false, degrees if true.

%related
_S3d_LocalRotateX
_S3d_LocalRotateY

%%================================================
%section
_S3d_GetLocalMatrix

%desc
Gets the current local matrix

%syntax
_S3d_GetLocalMatrix()

%return
Local matrix (2 dimensional array)

%related
_S3d_SetLocalMatrixEx

%%================================================
%section
_S3d_SetLocalMatrixEx

%desc
Sets the local matrix directly

%syntax
_S3d_SetLocalMatrixEx(ByRef $aMatrix)

%param
$aMatrix = New local matrix (2 dimensional array)

%related
_S3d_SetLocalMatrix
_S3d_GetLocalMatrix

%%================================================
%section
_S3d_GetPos

%desc
Converts 3D coordinates of a point into 2D coordinates

%syntax
_S3d_GetPos($nX, $nY, $nZ)

%param
$nX, $nY, $nZ = 3D coordinates of a point

%return
Success: Returns a two-element array containing the 2D coordinates ([0] = X, [1] = Y)
Failure: 0, @error = 1

%remarks
This function fails if the specified point is behind the camera.

%%================================================
%section
_S3d_MoveTo

%desc
Sets the current position

%syntax
_S3d_MoveTo($nX, $nY [, $nZ = Default])

%param
$nX, $nY, $nZ = New current position. see remarks

%return
Success: 1
Failure: 0, @error = 1

%remarks
If $nZ is omitted, $nX and $nY the current position is ($nX, $nY).
If $nZ is specified, this function converts ($nX, $nY, $nZ) into 2D and sets the current position.

This function fails if the specified point is behind the camera.

%related
_S3d_LineTo

%%================================================
%section
_S3d_Clear

%desc
Clears a Graphics object to a specified color

%syntax
_S3d_Clear($nColor = 0xFF000000)

%param
$nColor = *Alpha, Red, Green and Blue components of color

%return
Success: True
Failure: False

%%================================================
%section
_S3d_Line

%desc
Draws a line

%syntax
_S3d_Line($nX1, $nY1, $nZ1, $nX2, $nY2, $nZ2)

%param
$nX1, $nY1, $nZ1 = The coordinates of the starting point of the line
$nX2, $nY2, $nZ2 = The coordinates of the ending point of the line

%return
Success: True
Failure: 0, @error = 0 when _GDIPlus_GraphicsDrawLine failed; 1 when the line is behind the camera.

%remarks
This function failes if both of the two points are behind the camera.

%related
_S3d_LineTo
_S3d_Arrow

%%================================================
%section
_S3d_LineTo

%desc
Draws a line from the current position to the specified point

%syntax
_S3d_LineTo($nX, $nY, $nZ)

%param
$nX, $nY, $nZ = The coordinates of the ending point of the line

%return
Success: 1
Failure: 0, @error = 1

%remarks
If this function succeeds, the current position is set to the specified ending point.
This function failes if the specified point is behind the camera.

%related
_S3d_Line

%%================================================
%section
_S3d_Box

%desc
Draws a box

%syntax
_S3d_Box($nX1, $nY1, $nZ1, $nX2, $nY2, $nZ2)

%param
$nX1, $nY1, $nZ1 = The coordinates of the starting point
$nX2, $nY2, $nZ2 = The coordinates of the ending point


%%================================================
%section
_S3d_Arrow

%desc
Draws an arrow

%syntax
_S3d_Arrow($nX1, $nY1, $nZ1, $nX2, $nY2, $nZ2 [, $nLen = 30 [, $nAngle = 0.6 ]])

%param
$nX1, $nY1, $nZ1 = The coordinates of the starting point of the arrow
$nX2, $nY2, $nZ2 = The coordinates of the ending point of the arrow
$nLen = *The length of the arrow cap
$nAngle = *The width of the arrow cap in radians

%return
Success: 1
Failure: 0, @error = 1

%remarks
This function failes if both of the two points are behind the camera.

%%================================================
%section
_S3d_Circle

%desc
Draws or fills the circle

%syntax
_S3d_Circle($nX, $nY, $nZ, $nRad [, $fFill = False])

%param
$nX, $nY, $nZ = The coordinates of the center point of the circle
$nRad = Radius
$fFill = *If true, the circle is filled

%return
Success: 1
Failure: 0
@error = 0 : _GDIPlus_GraphicsFillEllipse or _GDIPlus_GraphicsDrawEllipse failed
@error = 1 : $nRad is negative or zero
@error = 2 : The center point of the circle is behind the camera

%%================================================
%section
_S3d_Polygon

%desc
Draws or fills a polygon

%syntax
_S3d_Polygon($aPoints [, $fFill = False])

%param
$aPoints = Array that specify the vertices of the polygon, see remarks
$fFill = *If true, the polygon is filled

%return
Success: 1
Failure: 0
@error = 0 : _GDIPlus_GraphicsFillPolygon or _GDIPlus_GraphicsDrawPolygon failed
@error = 1 : $aPoints is not an array
@error = 2 : Failed to convert the coordinates of $aPoints[@extended][0] - $aPoints[@extended][2]

%remarks
$aPoints must be in the following format:
{{{
$aPoints[0][0] : The number of points
$aPoints[n][0] : nth X
$aPoints[n][1] : nth Y
$aPoints[n][2] : nth Z
}}}

%related
_S3d_RegPolygon

%%================================================
%section
_S3d_RegPolygon

%desc
Draws or fills a regular polygon

%syntax
_S3d_RegPolygon($nX, $nY, $nZ, $nRad, $iNum [, $fFill = True])

%param
$nX, $nY, $nZ = The coordinates of the center point of the regular polygon
$nRad = Radius
$iNum = The number of the vertices
$fFill = *If true, the regular polygon is filled

%return
Success: 1
Failure: 0

%remarks
This function draws or fills a regular polygon on the XY plane when called without changing the local matrix.

%related
_S3d_Polygon
_S3d_Star

%%================================================
%section
_S3d_Star

%desc
Draws or fills a star

%syntax
_S3d_Star($nX, $nY, $nZ, $nRad1, $nRad2, $iNum [, $fFill = True])

%param
$nX, $nY, $nZ = The coordinates of the center point of the star
$nRad1 = Radius1
$nRad2 = Radius2
$iNum = $iNum * 2 is the number of the vertices
$fFill = *If true, the star is filled

%return
Success: 1
Failure: 0

%remarks
This function draws or fills a star on the XY plane when called without changing the local matrix.

%related
_S3d_RegPolygon

%%================================================
%section
_S3d_Square

%desc
Draws or fills a square

%syntax
_S3d_Square($nX1, $nY1, $nZ1, $nX2, $nY2, $nZ2, $nX3, $nY3, $nZ3, $nX4, $nY4, $nZ4 [, $fFill = True])

%param
$nX1, $nY1, $nZ1, $nX2, $nY2, $nZ2, $nX3, $nY3, $nZ3, $nX4, $nY4, $nZ4 = The coordinates of the vertices
$fFill = *If true, the square is filled

%return
Success: 1
Failure: 0, @error = 1

%remarks
This function failes if all of the specified points are behind the camera.

%related
_S3d_RibbonTo

%%================================================
%section
_S3d_MoveTo2

%desc
Sets the two current positions

%syntax
_S3d_MoveTo2($nXL, $nYL, $nZL, $nXR, $nYR, $nZR)

%param
$nXL, $nYL, $nZL, $nXR, $nYR, $nZR = The coordinates of the new current positions

%return
Success: 1
Failure: 0, @error = 1 if ($nXL, $nYL, $nZL) is behind the camera; 2 if ($nXR, $nYR, $nZR) is.

%remarks
This function is a plane version of _S3d_MoveTo.
This function failes if either of the specified point is behind the camera.

%related
_S3d_RibbonTo

%%================================================
%section
_S3d_RibbonTo

%desc
Fills a ribbon like plane

%syntax
_S3d_RibbonTo($nXL, $nYL, $nZL, $nXR, $nYR, $nZR)

%param
$nXL, $nYL, $nZL, $nXR, $nYR, $nZR = The coordinates of the new positions

%return
Success: 1
Failure: 0, @error = 1 if ($nXL, $nYL, $nZL) is behind the camera; 2 if ($nXR, $nYR, $nZR) is.

%remarks
This function is a plane version of _S3d_LineTo.

If this function succeeds, the current positions are set to the specified points.
This function failes if either of the specified point is behind the camera.

%related
_S3d_MoveTo2

%%================================================
%section
_S3d_String

%desc
Draws a string

%syntax
_S3d_String($sString, $nX, $nY, $nZ)

%param
$sString = String to be drawn
$nX, $nY, $nZ = The coordinate where the string will be drawn

%return
Success: 1
Failure: 0, @error = 0 if _GDIPlus_GraphicsDrawStringEx failed, 1 if ($nX, $nY, $nZ) is behind the camera.

%remarks
Before calling this function, Font and String Format must be specified using _S3d_SelectFont and _S3d_SelectFormat.

%related
_S3d_SelectFont
_S3d_SelectFormat


