Code name: Map Invoker

As Simon mentioned in previous post here, I am working on an application, which I am developing under the code name "Map Invoker".  It will generate random towns, from small little hamlets to large walled cities.  I've been concentrating on the algorithm side and am truely quite a ways towards a "feature complete" logic set.

So Simon was correct in stating that "He’s gone beyond proof of concept".  Soon I will be turning from generation to the interface so that all the parameters that I've included in the algorithms are exposed to the user so that the user can create an incredable range of different towns.

Once the paramter inputs are down and tested, then we will be looking into adding all the "garnish" that makes programs like this come alive.  So if you have any ideas, practical or "pie in the sky", I'd love to here them.  Either post your idea or email me at: SAUNDERL (at) HOTMAIL (dot) COM.

The Spiral Command - In Three Parts (Part #1)

The Spiral Command - In Three Parts (Part #1)
In this post and the next two posts, I will be building a spiral command.  In this post we will be dealing with the algorithm.  When we are done with this post, we will have a command that draws a spiral that would have 20 loops if it started in the middle, but we also told the algorithm to not draw the innermost 10 loops.  We have also hard currently coded the command to draw the spiral with a distance of 10 between each loop.

I will be using the name MYSPIRALM for this temporary command.  When finished, this will be the command for the macro version.

Note:  There is a naming convention that states if you have both a dialog driven command and a comand that is all command line for macros, the macro version ends with an M.

 Hardcoded values:

• Distance Between Loops: 10
• Number of Inner Loops Not Drawn: 10
• Total Number of Loops: 20
• Clockwise/Counter Clockwise: Clockwise
• Growth Between Loops: None

Our next post will implement RecData's to get the values that we currently are hardcoded.  Then, we will finish up with a dialog driven command.

Friday, August 20, 2010MyLine Command (A Complete Example)
We have finally reached the point where we can produce an entire example. In my previous post I explained how, conceptually, this command will work. Now, here is the actual code for the command along with a lot of comments.

I have also copied and commented out the definitions for the relevant elements that we are going to create.

I hope that you fire up Visual Studio and try building this code; if you are impatient though and want to just run it, here

Code Snippet - MySpiralM Command

1. ////////////////////////////////////////////////////////////////////////////
2. //
3. //    File Name: MySpiral.cpp
4. //    Written by: L. Lee Saunders
5. //    (C)2010 Beer & Pretzel Games
6. //    All rights reserved
7. //
8. ////////////////////////////////////////////////////////////////////////////
9.  
10. #include <windows.h>
11. #include <math.h>
12.  
13. extern "C"
14. {
15.     #include <xp.h>
16.     #include <Extend/Mysvc.h>
17. }
18.  
19. extern XP MyXP;
20.  
21. ////////////////////////////////////////////////////////////////////////////
22.   
23. void XPCALL DrawSpiral (int Result,int Result2,int Result3);
24. GPOINT2 CenterPoint;
25.  
26. FORMST(lpszCenterPoint,"Center Point:\0")
27.   
28. RDATA PCenterReq =
29.    { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&CenterPoint,
30.   (DWORD*)&lpszCenterPoint, RDC_XH, DrawSpiral, NULL, NULL, 0, NULL, 0};
31. ////////////////////////////////////////////////////////////////////////////
32.   
33.   
34. ////////////////////////////////////////////////////////////////////////////
35. void XPCALL MySpiralM (void)
36. {
37.     ReqData(&PCenterReq);  //get center point
38. }
39. ////////////////////////////////////////////////////////////////////////////
40.  
41.  
42. ////////////////////////////////////////////////////////////////////////////
43. void XPCALL DrawSpiral (int Result,int Result2,int Result3)
44. {
45.     if (Result != X_OK) { CmdEnd(); return; }
46.  
47.     float Growth = 1;
48.     float LoopDistance = 10;
49.  
50.     int Rotations = 20;
51.     int InnerLoopsToSkip = 10;
52.     const char * Direction = "0\0";
53.  
54.     pENTREC pEntRec;  //Create a new drawing database entity
55.     
56.     float CenterX = CenterPoint.x;
57.     float CenterY = CenterPoint.y;
58.  
59.     int iDirection;
60.  
61.     MarkUndo();
62.  
63.     // Insert an empty path into the drawing list
64.     pEntRec=DLApndE(NULL, ET_PATH2, sizeof(PATH2)+sizeof(GPOINT2));
65.  
66.     // Get the common stuff
67.     GetCStuff(pEntRec);
68.  
69.     // Set the smoothing to Parabolic Blend (through-point)
70.     pEntRec->Path.Path.SmType = SM_PB;
71.  
72.     // Set the centerpoint of the spiral
73.     pEntRec->Path.Path.Nodes[0].x = CenterPoint.x;    
74.     pEntRec->Path.Path.Nodes[0].y = CenterPoint.y;
75.  
76.     // How many points to draw per circle
77.     const double STEPS_PER_ROTATION = 50;
78.     
79.     // Amount to add to angle at each step
80.     double increment = M_PI/STEPS_PER_ROTATION;  // Splitting up
81.  
82.     double theta = 2*M_PI*InnerLoopsToSkip;  // This allows for an open area
83.     // inside the spiral
84.  
85.     // Determines if the loops rotates clockwise or counter clockwise
86.     iDirection = strcmp(Direction, "0") == 0 ? 1 : -1;
87.  
88.     while(theta < (Rotations * 2) * M_PI)
89.     {
90.         pEntRec=DLResize(pEntRec, pEntRec->Path.CStuff.ERLen +
91.           sizeof(GPOINT2));
92.  
93.         pEntRec->Path.Path.Nodes[pEntRec->Path.Path.Count].x=(float)
94.           (CenterX + theta * cos(theta) * (1/(M_PI * 2)) * LoopDistance *
95.           iDirection);
96.         pEntRec->Path.Path.Nodes[pEntRec->Path.Path.Count].y=(float)
97.           (CenterY + theta * sin(theta) * (1/(M_PI * 2)) * LoopDistance);
98.         
99.         pEntRec->Path.Path.EParm=(float)pEntRec->Path.Path.Count;
100.         pEntRec->Path.Path.Count++;
101.         
102.         LoopDistance = LoopDistance * Growth;
103.         theta = theta + increment; //If theta grows faster then increment,
104.         //it will have wider spaces between each loop    
105.     }
106.                 
107.     EDraw(pEntRec);  //Draw our line
108.     ShowChanges();   //Needed for CC3 to "Show Changes" to the DB
109.  
110.     CmdEnd();
111.     return;
112. }
113. ////////////////////////////////////////////////////////////////////////////

How to walk the "Drawing List"

In trying to decide what element of CC3 XP programming I was going to blog about next, I started to re-read all of the old posts on the cc2-dev-l email list @ groups.yahoo.com. 

Wow, I had forgotten how much valuable information was out there. If you have the time (And it will take a bit of time) just start at the beginning and read through the threads.  I promise that you will learn something – I did!

I found a request by Linda Kekumu.  It seemed that she had a large number of maps that had lots of Notes attached to them and they were wrong.  She needed a quick way to clear out all the notes on a map, instead of manually removing them one at a time.  Peter responded with this dash of code.

The reason I selected it for this post is that it is probably the smallest piece of code that displays how to use DLScan.  Now DLScan does exactly as the name says, it scans the “Drawing List” (i.e. the drawing database) and calls a function for every “identified” element.  I say “identified” because there are times when you only want to look at a subset of the entire Drawing List.

In this new XP command, we scan the Drawing List with the DLS_Std flag, telling DLScan that we want to scan the Drawing List for “all standard all non-erased elements”.

Then in our called function (ClearNotesScan) we check the EType of each identified  element (pEntRec) .  If the EType equals ET_Note, we know it is a Note and we call DLErase to remove the element from the Drawing List.

So, with this, you can now scan through a map and look at every identified element!

Code Snippet – MyClearNotes Command

1. /////////////////////////////////////////////////////////////////////////////
2. //
3. // Program: CC3DeveloperBlog.dll
4. // File Name: MyClearNotes.cpp
5. // Written by Peter Olsson (Copied here by L. Lee Saunders)
6. // (C)2010 Beer &amp; Pretzel Games
7. // All rights reserved
8. //
9. /////////////////////////////////////////////////////////////////////////////
10. 
    
11. #include <windows.h>
12. #include <math.h>
13. 
    
14. extern"C"
15. {
16.     #include <xp.h>
17.     #include <math.h>
18. }
19. extern XP MyXP;
20. /////////////////////////////////////////////////////////////////////////////
21. 
    
22. 
    
23. /////////////////////////////////////////////////////////////////////////////
24. DWORD XPCALL ClearNotesScan(hDLIST hDList, pENTREC pEntRec, PARM p1, PARM p2)
25. {
26.     //If the Entity Record is of type "Note" then erase the Entity from DL
27.     if(pEntRec->CStuff.EType==ET_NOTE) { DLErase(pEntRec); }
28.     return 0;
29. }
30. /////////////////////////////////////////////////////////////////////////////
31. 
    
32. 
    
33. /////////////////////////////////////////////////////////////////////////////
34. void XPCALL MyClearNotes(void)
35. {
36.     //Description copied from FCW32.TXT
37.     //---------------------------------------------------------------
38.     // ClearSel - Clear All Selection bits
39.     //---------------------------------------------------------------
40.     ClearSel();
41. 
    
42.     //This sets an undo point so that every action after this to the end of
43.     //the command will be reversed if the user selects UNDO.
44.     MarkUndo();
45. 
    
46.     //Drawing list scan. We are interested in only the first three parameters
47.     // Param #1: Drawing list - If null, it is the main list
48.     // Param #2: Our Callback function for every identified element in the DL
49.     // Param #3: DSFlags. How we identify what DL elements we want
50.     DLScan(NULL, ClearNotesScan, DLS_Std, 0, 0);
51. 
    
52.     //End the command
53.     CmdEnd();
54. }
55. /////////////////////////////////////////////////////////////////////////////

MyLine Command (A Complete Example)

We have finally reached the point where we can produce an entire example.   In my previous post I explained how, conceptually, this command will work.  Now, here is the actual code for the command along with a lot of comments.

I have also copied and commented out the definitions for the relevant elements that we are going to create.

I hope that you fire up Visual Studio and try building this code; if you are impatient though and want to just run it, here is the dll.

Code Snippet - MyLine Command (A Complete Example)

1. ////////////////////////////////////////////////////////////////////////////
2. //
3. //    Written by: L. Lee Saunders
4. //    Date: 8/15/2010
5. //    (C)2010 BeerAndPretzelGames.com
6. //    All rights reserved
7. //
8. ////////////////////////////////////////////////////////////////////////////
9. #include <windows.h>
10.  
11. extern "C"
12. {  
13.     #include <XP.H>
14.     #include <Extend/Mysvc.h>
15. }
16.  
17. #define XPID 0xF000
18.  
19. void XPCALL About(void);
20. void XPCALL MYLINE(void);
21.  
22. char CList[]="MYLINE\0";
23. PCMDPROC PList[]={About,MYLINE};
24.  
25. XP MyXP =
26.    { 0, CList, PList, 0, 0, 0, XPID, 0, 500, 0, 0, 500 };
27. ////////////////////////////////////////////////////////////////////////////
28.  
29.  
30. ////////////////////////////////////////////////////////////////////////////
31. FORMST(MyAPkt,"BLOG DLL commands:\n\n"
32.        "\tMYLINE - Duplicating the Line Command #s\n\0")
33.  
34. void XPCALL About (void)
35. {
36.     FormSt(&MyAPkt,RSC(FD_MsgBox));
37. }
38. ////////////////////////////////////////////////////////////////////////////
39.  
40.  
41. ////////////////////////////////////////////////////////////////////////////
42. void XPCALL MYLINE2 (int Result,int Result2,int Result3);
43. void XPCALL MYLINE3 (int Result,int Result2,int Result3);
44.  
45. //This is the definition of LINE2
46. //==========================================================================
47. //typedef struct
48. //{
49. //    CSTUFF    CStuff;              // entity properties
50. //    GLINE2    Line;                // line properties
51. //} LINE2;
52.  
53. //This is the definition of GLINE2
54. //==========================================================================
55. //typedef struct
56. //{
57. //    GPOINT2 p1;                    // starting point
58. //    GPOINT2 p2;                    // ending point
59. //} GLINE2;
60.  
61. //This is the definition of GPOINT2
62. //==========================================================================
63. //typedef struct
64. //{
65. //    float x;
66. //    float y;
67. //} GPOINT2;
68.  
69. //This is the definition of CSTUFF
70. //==========================================================================
71. //typedef struct
72. //{
73. //    int    ERLen;                    // entity record length
74. //    unsigned char    EType;          // entity type code
75. //    char    EFlags;                  // erase/select bits
76. //    char    EFlags2;                 // extra flags
77. //    unsigned char    EColor;         // entity color
78. //    unsigned char    EColor2;        // fill (2nd) color
79. //    char    EThick;                  // pen thickness 0..25.4 mm
80. //    short    WPlane;                 // workplane (0 = XY plane)
81. //    short    ELayer;                 // layer
82. //    short    ELStyle;                // line style (0=solid)
83. //    short    GroupID;                // group id (0 = not grouped)
84. //    short    EFStyle;                // fill style (0=hollow)
85. //    float    LWidth;                 // line width
86. //    int    Tag;                      // entity tag id
87. //} CSTUFF;
88.  
89. //This is the working structure that we will use to create all the lines
90. LINE2 BuildL = {
91.     sizeof(LINE2),                // entity record length
92.     ET_LINE2,                     // entity type code
93.     0,                            // erase/select bits
94.     0,                            // extra flags
95.     1,                            // entity color
96.     1,                            // fill (2nd) color
97.     0,                            // pen thickness 0..25.4 mm
98.     0,                            // workplane (0 = XY plane)
99.     1,                            // layer
100.     0,                            // line style (0=solid)
101.     0,                            // group id (0 = not grouped)
102.     0,                            // fill style (0=hollow)
103.     0.0,                          // line width
104.     0,                            // entity tag id
105.     0.0,                          // starting point: x
106.     0.0,                          // starting point: y
107.     1.0,                          // ending point: x
108.     1.0                           // ending point: y
109. };
110.  
111. FORMST(lpszFirstPoint,"1st point:\0")
112.  
113. FORMST(lpszNextPoint,"Next point:\0")
114.  
115. RDATA P1Req =
116.    { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&BuildL.Line.p1,
117.     (DWORD*)&lpszFirstPoint, RDC_XH, MYLINE2, NULL, NULL, 0, NULL, 0};
118.  
119. RDATA P2Req =
120.    { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&BuildL.Line.p2,
121.     (DWORD*)&lpszNextPoint, RDC_RBAND, MYLINE3, NULL, NULL, 0, NULL, 0};
122.  
123. ////////////////////////////////////////////////////////////////////////////
124.  
125.  
126. ////////////////////////////////////////////////////////////////////////////
127. void XPCALL MYLINE (void)
128. {
129.     ReqData(&P1Req);  //get first point
130. }
131. ////////////////////////////////////////////////////////////////////////////
132.  
133.  
134. ////////////////////////////////////////////////////////////////////////////
135. void XPCALL MYLINE2 (int Result,int Result2,int Result3)
136. {
137.     if (Result != X_OK) { CmdEnd(); return; } //If we did not get valid info
138.     
139.     MarkUndoAdd();  //Enable Undo
140.     NewCsrOrg(BuildL.Line.p1.x, BuildL.Line.p1.y);  //Set cursor origin
141.     ReqData(&P2Req);  //Get next point
142. }
143. ////////////////////////////////////////////////////////////////////////////
144.  
145.  
146. ////////////////////////////////////////////////////////////////////////////
147. void XPCALL MYLINE3 (int Result,int Result2,int Result3)
148. {
149.     pENTREC pEntRec;  //Create a new drawing database entity
150.  
151.     if (Result != X_OK) { CmdEnd(); return; } //If we did not get valid info
152.  
153.     //This gets all the current stuff like current color and assigns it
154.     //to our line entity.
155.     GetCStuff(&BuildL.CStuff);
156.  
157.     //Append a copy of our line to the DB and return a pointer to the new
158.     //entity in the database.  We assign it to pEntRec.
159.     pEntRec=DLApnd(NULL,(pENTREC)&BuildL);
160.     
161.     EDraw(pEntRec);  //Draw our line
162.     ShowChanges(); //Needed for CC3 to "Show Changes" to the DB
163.  
164.     BuildL.Line.p1.x=BuildL.Line.p2.x;  //move 2nd x to 1st x
165.     BuildL.Line.p1.y=BuildL.Line.p2.y;  //move 2nd y to 1st y
166.     
167.     NewCsrOrg(BuildL.Line.p1.x,BuildL.Line.p1.y);  //Set cursor origin
168.  
169.     ReqData(&P2Req);  //Get next point
170. }
171. ////////////////////////////////////////////////////////////////////////////
172.  
173.  
174. ////////////////// DllMain - XP initialization & Unload code ///////////
175. BOOL WINAPI DllMain (HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)
176. {
177.     switch (dwReason)
178.     {
179.         case DLL_PROCESS_ATTACH:
180.         {
181.             MyXP.ModHdl=hDLL;
182.             XPRegCmd(&MyXP);
183.             break;
184.         }
185.         case DLL_PROCESS_DETACH:
186.         {
187.             XPUnregCmd(&MyXP);
188.             break;
189.         }
190.     }
191.     return TRUE;
192. }
193. ////////////////////////////////////////////////////////////////////////////

Beads – How to Wait for Input

[Note: This is copied from the "FastCAD XP Programming Reference" that comes with the XP toolkit.  I copied this, with editing only for clarity, because it was so descriptive]

Nowhere in the Windows programming environment will you find a greater need to change your thinking than with regard to getting input.

In Windows, our programs receive messages that inform us of discrete user input - a mouse movement, button click, or a keyboard press. Other than dialog boxes, there is no way provided to wait for a complete word or line of text or other aggregate input in your program and then continue. We must write our program so that each keystroke is processed and then control is returned all the way to Windows.

This means that in a piece of code (creating a text entity, for example) we can not have one procedure that calls another to get a line of text and then continues with the next instruction when it is available, as would be done in a DOS or Unix program. The current position within that first command procedure is normally maintained on the stack, perhaps as a nested chain of procedure calls.

In Windows, after every event (such as a single key press), we have to return all the way up the stack back to Windows! This is why most Windows programs do all of their input through dialog boxes.

The FastCAD solution to this problem is to think of a command as a string of "beads" - little pieces of a command that each do one small part of the overall command, each a piece that can be done in response to an appropriate input event.

Lets take as an example a command to create a line entity. In traditional programming, its logic might be:

LineCommand:

prompt the user for the first point
- Get the first point if there was a problem getting it, end the command

prompt the user for the second point
- Get the second point if there was a problem getting it, end the command

Create the line entity

Append it to the drawing database

Draw the line entity

End the command

In FastCAD, we have an API service, ReqData, that handles data requests. We call ReqData with a packet that tells it about the data request, and then we go back to Windows.

When the data becomes available, ReqData will call another procedure specified in our original request packet to continue with our command. This means that we write our command as a series of procedures, linked together by RDATA packets, each one executing when its data becomes available, and returning to Windows when it needs to wait for more input.

The sequence looks like this:
==========================
Event: Action (Bead procedure):
- LINE function entered
- - Request first point by calling ReqData
- Line function ends

User enters the first request for a point:

Event: Action (Bead procedure):
- Second LINE function entered
- - Did the user cancel the request?
- - - End Command
- - Request second point by calling ReqData
- Second Line function ends

User enters the second request for a point:

Event: Action (Bead procedure):
- Third LINE function entered
- - Did the user cancel the request?
- - - End Command
- - Else
- - - Create the line entity
- - - Append it to the drawing database
- - - Draw the line entity
- - - End Command
-  Third Line function ends

The LINE command is implemented in 3 beads, each of which is called in response to a single event, such as a mouse click or a RETURN keypress. The ReqData service provides all of the intermediate beads that track mouse movement and build up strings of characters into words like "LINE" for you.

Next post, we will start to implement the LINE command.

Ok, you requested data, now what did you get?

Ok, so you have messed around with the RDATA function and you want to select an element, like a circle.  So you create a new RDATA function with the fallowing parameters:

• Cursor:  RDC_PICK
• Flags:  RDF_C
• Type:  RD_Pick1

 Now create a data store variable of type pEntRec.

A pEntRec type is a very important type in writing XP's.  The pEntRec type is the generic entity pointer that can point to any type of drawing entity.  So, if you selected a circle with your RDATA call, pEntRec will point to the the circle entry within the "Drawing Database"

The "Drawing Database" is the collection of all the visible elements in the map.  When we select elements, Campaign Cartographer returns a pointer to the selected element in the "Drawing Database".

Once you get a pointer to an entity, you can edit, interrogate or delete it.

Every entity shares some common data - appropriately named: CSTUFF

CStuff is defined as:

Code Snippet - CSTUFF

1. typedef struct
2. {
3.     int              ERLen;        // entity record length
4.     unsigned char    EType;        // entity type code
5.     char             EFlags;       // erase/select bits
6.     char             EFlags2;      // extra flags
7.     char             EColor;       // entity color
8.     char             EColor2;      // fill (2nd) color
9.     char             EThick;       // pen thickness 0..25.4 mm
10.     short            WPlane;       // workplane (0 = XY plane)
11.     short            ELayer;       // layer
12.     short            ELStyle;      // line style (0=solid)
13.     short            GroupID;      // group id (0 = not grouped)
14.     short            EFStyle;      // fill style (0=hollow)
15.     float            LWidth;       // line width
16.     int              Tag;          // entity tag id
17. } CSTUFF;

For example you have a pEntRec named pENTREC and you want to get the entities color:

pENTREC->CStuff.EColor

Requesting data from CC3 - RDATA

Last post I introduced the two most important functions exposed by CC3: RDATA & FORMST.

In this post I'll discuss the internals of RDATA.

Here are the important elements you need to configure for every time you declare an RDATA.

• Name - This is simply the name the holds all the separate RDATA elements together
• Type - This is where you declare what kind of data you are requesting
• Flags - These flags are the switches that tweak the RDATA call to do exactly what you want
• Data Store - Where to "put" what you have requested after it has been selected
• Prompt - This is the text that will be displayed to the user
• FormSt declaration - This is where you decide if you want to include the prompt declaration. If you already have exactly the prompt you want already declared, you can reuse it instead of creating a new one
• Cursor - Obviously selecting a single item you want a different cursor than if you want them to type in some text
• Return Procedure

When I first started to write XP's, Super Guru Peter Olsen sent me a little tool that he wrote to automatically generate the RDATA call. When I was preparing for this post, I asked Peter if he still had the app. Well, he did, but he suggested that I create an online version of the tool. So, here is a Silverlight 4 application that generates an RDATA structure for you.



In my next post, I'll use the tool to generate our RDATA and select our first element. Plus, we will start to discuss what it is exactly, that we get back from our ReqData call.