This reference page is linked to from the following overview topics: General Best Practices, How Objects are Drawn in the Viewport, Cameras, Hit Lists, Node Level Hit Testing, Getting and Setting User Preferences, Snapping.
Detailed Description
- See also:
- List
of Snap Flags, Class Ray, Class Point3, Class IPoint2, Class Matrix3, Class
ModContext, Class HitData, Class GraphicsWindow, Class INode.
- Description:
- This class provides methods to access properties of the viewport, convert points between viewport and world coordinates, snap points and lengths, etc. Many methods associated with hit testing are also here. All the methods of this class are implemented by the system.
- Method Groups:
- See Method Groups for Class ViewExp.
#include <maxapi.h>
Inheritance diagram for ViewExp:
Public Types |
|
| enum | { kEXECUTE_GET_VIEWEXP_10 = 0, kEXECUTE_GET_VIEWPORT_ID = 1, kEXECUTE_GET_VIEWEXP_11 = 2, kEXECUTE_GET_VIEWEXP_13 = 3 } |
Public Member Functions |
|
| virtual Point3 | GetPointOnCP (const IPoint2 &ps)=0 |
| virtual Point3 | SnapPoint (const IPoint2 &in, IPoint2 &out, Matrix3 *plane2d=NULL, DWORD flags=0)=0 |
| virtual float | SnapLength (float in)=0 |
| virtual float | GetCPDisp (const Point3 base, const Point3 &dir, const IPoint2 &sp1, const IPoint2 &sp2, BOOL snap=FALSE)=0 |
| virtual GraphicsWindow * | getGW ()=0 |
| virtual int | IsWire ()=0 |
| virtual Rect | GetDammageRect ()=0 |
| virtual Point3 | MapScreenToView (IPoint2 &sp, float depth)=0 |
| virtual void | MapScreenToWorldRay (float sx, float sy, Ray &ray)=0 |
| virtual BOOL | SetAffineTM (const Matrix3 &m)=0 |
| virtual void | GetAffineTM (Matrix3 &tm)=0 |
| virtual int | GetViewType ()=0 |
| virtual BOOL | IsPerspView ()=0 |
| virtual float | GetFOV ()=0 |
| virtual float | GetFocalDist ()=0 |
| virtual void | SetFocalDist (float fd)=0 |
| virtual float | GetScreenScaleFactor (const Point3 worldPoint)=0 |
| virtual float | GetFPS ()=0 |
| Get the FPS from the active viewport.
|
|
| virtual float | GetVPWorldWidth (const Point3 wPoint)=0 |
| virtual Point3 | MapCPToWorld (const Point3 cpPoint)=0 |
| virtual void | GetConstructionTM (Matrix3 &tm)=0 |
| virtual void | SetGridSize (float size)=0 |
| virtual float | GetGridSize ()=0 |
| virtual BOOL | IsGridVisible ()=0 |
| virtual int | GetGridType ()=0 |
| virtual INode * | GetViewCamera ()=0 |
| virtual void | SetViewCamera (INode *camNode)=0 |
| virtual void | SetViewUser (BOOL persp)=0 |
| virtual INode * | GetViewSpot ()=0 |
| virtual void | SetViewSpot (INode *spotNode)=0 |
| virtual void | ClearHitList ()=0 |
| virtual INode * | GetClosestHit ()=0 |
| virtual INode * | GetHit (int i)=0 |
| virtual int | HitCount ()=0 |
| virtual void | LogHit (INode *nr, ModContext *mc, DWORD dist, ulong info, HitData *hitdat=NULL)=0 |
| virtual HitLog & | GetSubObjHitList ()=0 |
| virtual void | ClearSubObjHitList ()=0 |
| virtual int | NumSubObjHits ()=0 |
| virtual void | CtrlLogHit (INode *nr, DWORD dist, ulong info, DWORD infoExtra)=0 |
| virtual CtrlHitLog & | GetCtrlHitList ()=0 |
| virtual void | ClearCtrlHitList ()=0 |
| virtual float | NonScalingObjectSize ()=0 |
| virtual BOOL | setBkgImageDsp (BOOL onOff)=0 |
| virtual int | getBkgImageDsp (void)=0 |
| virtual void | setSFDisplay (int onOff)=0 |
| virtual int | getSFDisplay (void)=0 |
| virtual HWND | GetHWnd ()=0 |
| virtual BOOL | IsActive ()=0 |
| virtual BOOL | IsEnabled ()=0 |
| virtual void | TrackImplicitGrid (IPoint2 m, Matrix3 *mat=NULL, ULONG hitTestFlags=0)=0 |
| virtual void | CommitImplicitGrid (IPoint2 m, int mouseflags, Matrix3 *mat=NULL)=0 |
| virtual void | ReleaseImplicitGrid ()=0 |
| virtual void | InvalidateRect (const Rect &rect)=0 |
| virtual INT_PTR | Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0) |
Member Enumeration Documentation
| anonymous enum |
- Enumerator:
-
kEXECUTE_GET_VIEWEXP_10 Command id to be passed to ViewExp::Execute in order to get the viewport's ViewExp10 interface.
kEXECUTE_GET_VIEWPORT_ID Command id to be passed to ViewExp::Execute in order to get the viewport's unique ID (different from its index)
kEXECUTE_GET_VIEWEXP_11 Command id to be passed to ViewExp::Execute in order to get the viewport's ViewExp11 interface.
kEXECUTE_GET_VIEWEXP_13 Command id to be passed to ViewExp::Execute in order to get the viewport's ViewExp13 interface.
{
kEXECUTE_GET_VIEWEXP_10 = 0,
kEXECUTE_GET_VIEWPORT_ID = 1,
kEXECUTE_GET_VIEWEXP_11 = 2,
kEXECUTE_GET_VIEWEXP_13 = 3,
};
Member Function Documentation
- Remarks:
- Returns a point in world space on the current construction plane based on the specified screen coordinate.
- Parameters:
-
ps The 2D screen point to convert to a 3D world space coordinate.
- Returns:
- The world space coordinate on the current construction plane.
| virtual Point3 SnapPoint | ( | const IPoint2 & | in, |
| IPoint2 & | out, | ||
| Matrix3 * | plane2d = NULL, |
||
| DWORD | flags = 0 |
||
| ) | [pure virtual] |
- Remarks:
- Given a 2D screen coordinate, this method returns a 3D point on the current construction plane based on the current snap settings and flags passed.
- Parameters:
-
in The 2D screen coordinate to snap. out The snapped 2D screen coordinate. This is used if you need to move the mouse position to the snapped location. plane2d This optional argument allows you to use any plane (not just the current construction plane). flags See List of Snap Flags.
- Returns:
- The snapped 3D point in construction plane coordinates.
| virtual float SnapLength | ( | float | in | ) | [pure virtual] |
- Remarks:
- Given the distance passed, this method snaps the length to the nearest snap increment and returns the snapped distance.
- Parameters:
-
in The input distance to be snapped.
- Returns:
- The snapped distance.
| virtual float GetCPDisp | ( | const Point3 | base, |
| const Point3 & | dir, | ||
| const IPoint2 & | sp1, | ||
| const IPoint2 & | sp2, | ||
| BOOL | snap = FALSE |
||
| ) | [pure virtual] |
- Remarks:
- This method returns a length in world space given a start screen point, an end screen point, a base point and a direction vector. For example, when creating a cylinder, the user clicks the mouse down to define the center point of the cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This method is used to return intermediate and final heights for the cylinder based on the initial base point, the direction vector (the Z axis), the start mouse point, and the current point the user is interactively adjusting.
- Parameters:
-
base Base point in object space. dir Direction vector in object space. sp1 Screen start point. This is the point where the user clicked down with the mouse. sp2 Screen end point. This is the point where the user let up the mouse. snap
- Returns:
- The length in world space based on the screen points and their projection onto the direction vector.
- Sample Code:
-
From /MAXSDK/SAMPLES/OBJECTS/CYL.CPP in CylinderObjCreateCallBack::proc
float h = vpt->SnapLength(vpt->GetCPDisp(p[1],Point3(0,0,1),sp1,m));
| virtual GraphicsWindow* getGW | ( | ) | [pure virtual] |
- Remarks:
- Returns a pointer to the instance of GraphicsWindow associated with
this viewport.
Note: A GraphicsWindow always has a transform associated with it, for faster object-to-screen space conversions. The GraphicsWindow * returned by this method may have a non-identity transform already in place. A developer can call gw->setTransform() with a node's transform for fast work in Display routines. But this value must be explicitly set to the identity for world-to-screen displays.
| virtual int IsWire | ( | ) | [pure virtual] |
- Remarks:
- Determines if this viewport is in wire-frame rendering mode (as opposed to a shaded mode).
- Returns:
- Nonzero if the viewport is in wire-frame rendering mode; otherwise 0.
| virtual Rect GetDammageRect | ( | ) | [pure virtual] |
- Remarks:
- Returns the damaged rectangle of the viewport. This is the area that needs to be updated on the next screen refresh. This can be used for example, to pass into the Mesh method render() to only display the damaged area of the object. A developer could also use this in the implementation of their own Display() method.
- Sample Code:
-
int SimpleObject::Display(TimeValue t, INode* inode, ViewExp *vpt, int flags) { if (!OKtoDisplay(t)) return 0; GraphicsWindow *gw = vpt->getGW(); Matrix3 mat = inode->GetObjectTM(t); UpdateMesh(t); // UpdateMesh() just calls BuildMesh() gw->setTransform(mat); mesh.render(gw, inode->Mtls(), (flags&USE_DAMAGE_RECT) ? &vpt->GetDammageRect() : NULL, COMP_ALL, inode->NumMtls()); return(0); }
- Remarks:
- Given a point on the screen (in window coordinates), and a depth in view coordinates, this method maps the point into view coordinates. This is just a scaling operation for parallel projections, but involves a divide by Z for perspective projections.
- Parameters:
-
sp Point in window coordinates. depth Depth in view coordinates.
- Returns:
- Point in view coordinates.
- Sample Code:
-
Point3 p0 = vpt->MapScreenToView(mBase,GetPerspMouseSpeed());
| virtual void MapScreenToWorldRay | ( | float | sx, |
| float | sy, | ||
| Ray & | ray | ||
| ) | [pure virtual] |
- Remarks:
- Creates a Ray in world space passing through the specified pixel directed toward the scene in the direction of view.
| virtual BOOL SetAffineTM | ( | const Matrix3 & | m | ) | [pure virtual] |
- Remarks:
- This method sets the viewport affine transformation and returns TRUE if the view is a user view (isometric or perspective). If the view is not a user view then the transformation is not changed and the method returns FALSE. See SetViewUser() below.
- Parameters:
-
m The transformation matrix to set.
| virtual void GetAffineTM | ( | Matrix3 & | tm | ) | [pure virtual] |
- Remarks:
- This method retrieves the affineTM which transforms from World coordinates to View coordinates. See the sample code below for an example of its use.
- Parameters:
-
tm The matrix to hold the affine TM. // This routine returns the view direction from the active viewport. Point3 Utility::GetViewDirection() { Matrix3 aTM, coordSysTM; ViewExp *ve = ip->GetActiveViewport(); // The affine TM transforms from world coords to view coords // so we need the inverse of this matrix ve->GetAffineTM(aTM); coordSysTM = Inverse(aTM); // The Z axis of this matrix is the view direction. Point3 viewDir = coordSysTM.GetRow(2); ip->ReleaseViewport(ve); return viewDir; }Note: You can also get the view position from this matrix. For example, in the above code, the statement: Point3 viewPt = coordSysTM.GetRow(3); gets the point in space the view is taken from.
| virtual int GetViewType | ( | ) | [pure virtual] |
- Remarks:
- Returns the type of view. One of the following values:
enum ViewType {
VIEW_LEFT,VIEW_RIGHT,VIEW_TOP,VIEW_BOTTOM,VIEW_FRONT,VIEW_BACK,
VIEW_ISO_USER, VIEW_PERSP_USER, VIEW_CAMERA, VIEW_GRID, VIEW_NONE,
VIEW_TRACK, VIEW_SPOT, VIEW_SHAPE, VIEW_SCHEMATIC, VIEW_OTHER
};
| virtual BOOL IsPerspView | ( | ) | [pure virtual] |
- Remarks:
- Returns TRUE if the viewport is a perspective view; otherwise returns FALSE.
| virtual float GetFOV | ( | ) | [pure virtual] |
- Remarks:
- Returns the field of view of a perspective viewport in
radians.
| virtual float GetFocalDist | ( | ) | [pure virtual] |
- Remarks:
- Returns the focal distance of a perspective view.
| virtual void SetFocalDist | ( | float | fd | ) | [pure virtual] |
- Remarks:
- Sets the focal distance of a perspective view.
- Parameters:
-
fd Specifies the focal distance to set.
| virtual float GetScreenScaleFactor | ( | const Point3 | worldPoint | ) | [pure virtual] |
- Remarks:
- Returns the screen scale factor for a point given in world coordinates. This factor gives the width in world-space units at the point's distance of the viewport.
- Parameters:
-
worldPoint The point in world coordinates.
- Returns:
- The screen scale factor in world space units.
| virtual float GetFPS | ( | ) | [pure virtual] |
Get the FPS from the active viewport.
- Returns:
- Return the frame per second of the active viewport.
| virtual float GetVPWorldWidth | ( | const Point3 | wPoint | ) | [pure virtual] |
- Remarks:
- Returns the viewport screen width factor in world space at a point in world space.
- Parameters:
-
wPoint The point in world space.
- Returns:
- The viewport screen width factor in world space.
- Remarks:
- Given a point on the construction plane this method returns the corresponding world space point. For example, if you use GetPointOnCP() to convert a screen coordinate to a point on the construction plane, you could then call this method to convert that point on the construction plane to a world space point.
- Parameters:
-
cpPoint The point on the construction plane.
- Returns:
- The world space point.
| virtual void GetConstructionTM | ( | Matrix3 & | tm | ) | [pure virtual] |
- Remarks:
- Retrieves the transformation matrix of the construction plane.
- Parameters:
-
tm The transformation matrix is returned here.
| virtual void SetGridSize | ( | float | size | ) | [pure virtual] |
- Remarks:
- Sets the size of the construction grid spacing.
- Parameters:
-
size Specifies the grid spacing.
| virtual float GetGridSize | ( | ) | [pure virtual] |
- Remarks:
- Returns the construction grid spacing. This is the grid spacing on a per viewport basis. It is dependent on how far zoomed in or out the user is. This is the exact same value that you can see in the right most status panel below the viewports.
| virtual BOOL IsGridVisible | ( | ) | [pure virtual] |
- Remarks:
- Returns TRUE if the grid is turned on for this viewport;
otherwise FALSE.
| virtual int GetGridType | ( | ) | [pure virtual] |
- Remarks:
- Returns the grid type. One of the following values (from
OBJECT.H):
GRID_PLANE_NONE
GRID_PLANE_TOP
GRID_PLANE_LEFT
GRID_PLANE_FRONT
GRID_PLANE_BOTTOM
GRID_PLANE_RIGHT
GRID_PLANE_BACK
| virtual INode* GetViewCamera | ( | ) | [pure virtual] |
- Remarks:
- Returns the INode pointer of the camera associated with this viewport. If this is not a camera view then NULL is returned.
| virtual void SetViewCamera | ( | INode * | camNode | ) | [pure virtual] |
- Remarks:
- Set this viewport to a camera view.
- Parameters:
-
camNode The camera node to set.
| virtual void SetViewUser | ( | BOOL | persp | ) | [pure virtual] |
- Remarks:
- This method sets the viewport to be a user view, with the persp argument indicating whether this should be a perspective or iso view. Note that the user viewport defaults are used for field-of-view, etc.
- Parameters:
-
persp TRUE for perspective; FALSE for isometric.
| virtual INode* GetViewSpot | ( | ) | [pure virtual] |
- Remarks:
- Returns the INode pointer of the spotlight associated with this viewport. If this is not a spotlight view then NULL is returned.
| virtual void SetViewSpot | ( | INode * | spotNode | ) | [pure virtual] |
- Remarks:
- Set this viewport to a spotlight view.
- Parameters:
-
spotNode The spotlight node to set.
| virtual void ClearHitList | ( | ) | [pure virtual] |
- Remarks:
- Implemented by the System.
Clears the list of node level hit records.
| virtual INode* GetClosestHit | ( | ) | [pure virtual] |
- Remarks:
- Implemented by the System.
Returns the INode pointer of the node that was the closest of all those hit. If none were hit, NULL is returned.
| virtual INode* GetHit | ( | int | i | ) | [pure virtual] |
- Remarks:
- Returns the INode pointer of the 'i-th' node level hit.
- Parameters:
-
i The index of the hit to retrieve.
| virtual int HitCount | ( | ) | [pure virtual] |
- Remarks:
- Implemented by the System.
Returns the number of hits recorded by the last node level hit test.
| virtual void LogHit | ( | INode * | nr, |
| ModContext * | mc, | ||
| DWORD | dist, | ||
| ulong | info, | ||
| HitData * | hitdat =
NULL |
||
| ) | [pure virtual] |
- Remarks:
- Implemented by the System.
This method records a sub-object level hit record with the system using the specified parameters. This hit can later be retrieved using the method GetSubObjHitList() and the methods of class HitLog.
- Parameters:
-
nr The node that was hit. mc The ModContext of the modifier. dist The 'distance' of the hit. What the distance actually represents depends on the rendering level of the viewport. For wireframe modes, it refers to the distance in the screen XY plane from the mouse to the sub-object component. In a shaded mode, it refers to the Z depth of the sub-object component. In both cases, smaller values indicate that the sub-object component is 'closer' to the mouse cursor. info Identifies the sub-object component that was hit. hitdat If the info data member is insufficient to indicate the sub-object component that was hit, pass an instance of the HitData class that contains the needed information.
| virtual HitLog& GetSubObjHitList | ( | ) | [pure virtual] |
- Remarks:
- Returns the sub-object hit list. See Class HitLog.
| virtual void ClearSubObjHitList | ( | ) | [pure virtual] |
- Remarks:
- Clears the sub-object hit list. This deletes all previously saved HitRecords.
| virtual int NumSubObjHits | ( | ) | [pure virtual] |
- Remarks:
- Returns the number of sub-object hits recorded.
| virtual void CtrlLogHit | ( | INode * | nr, |
| DWORD | dist, | ||
| ulong | info, | ||
| DWORD | infoExtra | ||
| ) | [pure virtual] |
- Remarks:
- This method records a controller sub-object level hit record with the system using the specified parameters. This hit can later be retrieved using the method GetCtrlHitList() and the methods of class CtrlHitLog.
- Parameters:
-
nr The node that was hit. dist The 'distance' of the hit. What the distance actually represents depends on the rendering level of the viewport. For wireframe modes, it refers to the distance in the screen XY plane from the mouse to the sub-object component. In a shaded mode, it refers to the Z depth of the sub-object component. In both cases, smaller values indicate that the sub-object component is 'closer' to the mouse cursor. info A general unsigned long value. Most controllers will just need this to identity the sub-object element. The meaning of this value (how it is used to identify the element) is up to the plug-in. infoExtra If the above hitInfo data member is not sufficient to describe the sub-object element this data member may be used as well.
| virtual CtrlHitLog& GetCtrlHitList | ( | ) | [pure virtual] |
- Remarks:
- Returns the list of controller gizmo hits recorded. See Class CtrlHitLog.
| virtual void ClearCtrlHitList | ( | ) | [pure virtual] |
- Remarks:
- Clears the controller hit list. This deletes all the HitRecords previously recorded.
| virtual float NonScalingObjectSize | ( | ) | [pure virtual] |
- Remarks:
- The value returned from this method may be used as a scale
factor that will counteract the viewport zoom. For example, lights,
cameras, and tape helper objects use this factor so the size of the
node in the scene remains constant when the viewport is zoomed in
and out.
This value is affected by the 'Non-Scaling Object Size' spinner in the Viewport Preferences dialog, so the user has some control over this as well.
- Sample Code:
- This sample is from /MAXSDK/SAMPLES/OBJECTS/TAPEHELP.CPP. The
computed matrix is used in several places like displaying,
snapping, hit testing, etc.
void TapeHelpObject::GetMat(TimeValue t, INode* inode, ViewExp* vpt, Matrix3& tm) { tm = inode->GetObjectTM(t); tm.NoScale(); float scaleFactor = vpt->NonScalingObjectSize() * vpt->GetVPWorldWidth(tm.GetTrans())/(float)360.0; tm.Scale(Point3(scaleFactor,scaleFactor,scaleFactor)); }
| virtual BOOL setBkgImageDsp | ( | BOOL | onOff | ) | [pure virtual] |
- Remarks:
- This method is used to turn on and off the background image display in this viewport. Note that it is necessary to redraw the viewports in order to see the effect of this method. Use the method Interface::RedrawViews() to do this.
- Parameters:
-
onOff TRUE to turn the background image on; FALSE to turn it off.
- Returns:
- TRUE if the image was set; otherwise FALSE.
| virtual int getBkgImageDsp | ( | void | ) | [pure virtual] |
- Remarks:
- Returns nonzero if the background image is displayed in this viewport; otherwise 0.
| virtual void setSFDisplay | ( | int | onOff | ) | [pure virtual] |
- Remarks:
- This method may be used to turn the safe frame display on and off in this viewport.
- Parameters:
-
onOff Nonzero to turn on the safe frame; zero to turn it off.
| virtual int getSFDisplay | ( | void | ) | [pure virtual] |
- Remarks:
- Returns nonzero if the safe frame is displayed in this viewport; otherwise 0.
| virtual HWND GetHWnd | ( | ) | [pure virtual] |
- Remarks:
- This returns the window handle of the viewport - this is the transparent window that catches mouse input. Note that this window handle is different than the handle that can be retrieved from the viewport's GraphicsWindow. getGW()->getHWnd() is the window that things are drawn on.
- Returns:
- The window handle of the viewport.
| virtual BOOL IsActive | ( | ) | [pure virtual] |
- Remarks:
- Returns TRUE if the viewport is the active on; otherwise FALSE.
| virtual BOOL IsEnabled | ( | ) | [pure virtual] |
- Remarks:
- Returns TRUE if the viewport is enabled; FALSE if disabled.
| virtual void TrackImplicitGrid | ( | IPoint2 | m, |
| Matrix3 * | mat = NULL, |
||
| ULONG | hitTestFlags =
0 |
||
| ) | [pure virtual] |
- Remarks:
- If AutoGrid is enabled, this method determines a grid coordinate system by casting a ray into the scene through the screen coordinate m, obtaining a surface normal from the closest node , and using the "arbitrary axis algorithm" to orient the xy axes. You can get this coordinate system back by passing in a pointer to a matrix. A tripod is displayed in the viewports showing the orientation.
- Parameters:
-
m The 2D screen point that the user clicked on. mat The implicit grid coordinate system matrix can be retrieved by passing a pointer to a matrix here. hitTestFlags See Scene and Node Hit Testing Flags.
- Remarks:
- If AutoGrid is enabled, this method creates a grid and activates it. The mouseflags parameter is used to determine if the ALT key is down. If it is, this grid will not be deactivated in ReleaseImplicitGrid()(below).
- Parameters:
-
m The 2D screen point that the user clicked on. mouse flags These flags describe the state of the mouse buttons. See List of Mouse Callback Flags. mat Developers can get the implicit grid coordinate system back by passing in a pointer to a matrix here.
| virtual void ReleaseImplicitGrid | ( | ) | [pure virtual] |
- Remarks:
- This method deactivates an implicit grid and restores the previously active grid. If the implicit grid was committed with ALT-key held down, then this call does nothing.
| virtual void InvalidateRect | ( | const Rect & | rect | ) | [pure virtual] |
- Remarks:
- This is a better way method to invalidate a viewport only if the area define by the Rect argument is not the whole size of the viewport. Calling InvalidateRect on a Rect defined like this: rect.top = 0; rect.bottom = gw->getWinSizeY(); rect.left = 0; rect.right = gw->getWinSizeX(); Will have the same effect of invalidating the viewport.
- Parameters:
-
rect The Rect that define the region on the viewport to be invalidated.
| virtual INT_PTR Execute | ( | int | cmd, |
| ULONG_PTR | arg1 = 0, |
||
| ULONG_PTR | arg2 = 0, |
||
| ULONG_PTR | arg3 = 0 |
||
| ) | [inline, virtual] |
- Remarks:
- This is a general purpose function that allows the API to be extended in the future. The 3ds Max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.
- Parameters:
-
cmd The index of the command to execute. arg1 Optional argument 1. See the documentation where the cmd option is discussed for more details on these parameters. arg2 Optional argument 2. arg3 Optional argument 3.
- Returns:
- An integer return value. See the documentation where the cmd option is discussed for more details on the meaning of this value.
{
UNUSED_PARAM(cmd);
UNUSED_PARAM(arg1);
UNUSED_PARAM(arg2);
UNUSED_PARAM(arg3);
return 0;
}
