ArchiCAD 19에 대한 GDL 애드온 개발하는 방법

소개

이 문서에 설명된 애드온 매커니즘은 GDL 스크립트를 통해 파일 동작을 사용할 수 있게 해줍니다.

애드온은 위의 목록에 나온 기능을 구현하기 위한 모든 필수 리소스들을 가진 하나의 파일입니다. 동봉된 패키지는 그러한 애드온들을 개발하기 위한 모든 필수 지원을 제공합니다.

이 문서는 당신이 C 언어에 익숙한 프로그래머이며 GDL 프로그래밍(특히 GDL 파일 동작)에 대한 약간의 경험을 갖고 있다고 가정합니다. GDL에 대한 정보는 ArchiCAD 패키지의 일부인 GDL 레퍼런스 가이드를 참조하시기 바랍니다.

이 문서의 구조는 주로 2가지 부분으로 구성되어 있습니다:

애드온의 사용법: 설치하는 장소, 실행하는 방법;
애드온 개발하기: 당신이 작성할 필요가 있는 함수들의 종류가 무엇인지, 당신이 사용할 수 있는(또는 없는) ArchiCAD 및 표준 라이브러리 함수들의 종류가 무엇인지, 예제 리소스를 다 써버리는 방법, 애드온을 컴파일 및 링크하는 방법.

이 문서의 정보를 표시할 다양한 관행을 찾게 될 것입니다. 특수 단어와 표현들은 특정 글꼴이나 스타일로 나타납니다.

모든 코드 리스팅, 예약된 단어들, 실제 data structure, 상수, 필드, 파라미터, 루틴의 이름은 항상 Courier체로 나옵니다.
bold로 표시된 단어와 수식들은 핵심 용어나 개념입니다.
일부 특수 용어들은 italic으로 표시됩니다.

애드온 설치하기

당신이 ArchiCAD를 실행할 때, 다음과 같이 애드온 들을 찾습니다:

홈 폴더 안에 Add-Ons 폴더를 검색합니다. (즉, 설치한 곳부터 검색함);
Macintosh의 경우, 만약 Add-Ons 폴더가 없으면 System Folder/Graphisoft 폴더 안에도 찾습니다.
Windows의 경우, Add-Ons 폴더가 없으면 레지스트리의 키 'HKEY_CURRENT_USER\Software\Graphisoft\ArchiCAD 19\ArchiCAD 19 xxx' 안에 있는 'Graphisoft Shared Folder'에 지정된 폴더 중 하나를 검색합니다.

경고! 만약 System/Graphisoft/Add-Ons 안에 (Windows: 레지스트리에서 지정된 폴더 안의 Add-Ons 내부) 유용한 애드온들을 가지고 있으며 정말로 그것들을 사용하려고 한다면, ArchiCAD의 홈 폴더 안에 Add-Ons 서브폴더를 만들지 마십시오!

만약 ArchiCAD가 어디에선가 Add-Ons 폴더를 찾으면, 해당 검색 파일들을 그 폴더와 서브폴더에서 모두 수집합니다.

검색된 모든 파일은 유효한 ArchiCAD 애드온으로 간주되기 위해 몇 가지 테스트를 거쳐야 합니다.

1. 파일 생성자 및 타입

GDL 애드온은 생성자가 'GSGD'이며 파일 타입이 '.GDX'인 공유 라이브러리여야 합니다. (Windows에서는 DLL) Macintosh에서는 링크를 호출할 때 "-t '.GDX' -c 'GSGD'" 옵션을 줌으로써 링크 시간에 이 속성들을 쉽게 세트할 수 있습니다. Windows에서는 ResConv.EXE 유틸리티를 '-RGSGD-.GDX ' 옵션과 함께 사용합니다.

2. 'ACNF'(32500) 리소스

모든 애드온들은 리소스 ID가 32500인 'ACNF'라는 리소스를 반드시 갖고 있어야 합니다. 이것은 애드온이 무엇을 하는지에 대한 ArchiCAD의 정보 레코드입니다. 이 리소스의 구조는 이 문서 뒷부분에 소개 및 설명하겠습니다.

ArchiCAD는 위의 요구사항들을 이행했는지 확인할 것입니다. 만약 어느 하나라도 바르지 않거나 누락되었다면, 해당 파일은 ArchiCAD의 유효한 애드온이라고 간주되지 않을 것입니다.

GDL 애드온 실행하기

GDL 애드온들은 GDL이 OPEN, INPUT, OUTPUT, CLOSE 또는 INITADDONSCOPE, PREPAREFUNCTION, CALLFUNCTION, CLOSEADDONSCOPE GDL 스크립트 커맨드를 적절한 파라미터와 함께 인터프리트 할 때 호출됩니다. REQUEST 커맨드를 인터프리트 할 때 1번째 파라미터가 request 자체이면, request가 ArchiCAD에서 구현되지 않은 경우 GDL은 확장을 관리합니다.

GDL 애드온 개발하기

당신이 애드온을 개발할 때, 당신은 수많은 함수들을 작성하고 그것들을 패키지에서 발견되는 라이브러리에 링크해야 합니다. 당신의 함수들은 파일로부터 데이터를 읽기/쓰기 하거나 다른 정보를 제공합니다. (GDL)

라이브러리 함수들은 ArchiCAD와 통신을 유지해야 합니다; 그리고 ArchiCAD 자체는 전체 GDL 인터프리트 과정을 통제합니다.

그룹 초기화/청소하기

GDL 스크립트로부터 OPEN 또는 INITADDONSCOPE (파일) 커맨드가 먼저 인터프리트 될 때마다 ArchiCAD는 해당 애드온을 메모리에 로드합니다. (만약 아직도 로드되지 않았다면)

라이브러리 (모든 애드온이 링크되어야 함) 안에 포함된 기능은 ArchiCAD와 통신하기 위해 환경을 설정합니다.

만약 통신 채널들을 설정하는 동안 오류가 발생하지 않는다면 애드온의 Initialize () 함수는 ArchiCAD에 의해 호출될 것입니다. 당신은 이 함수를 당신 코드의 메인 엔트리 포인트로 사용할 수 있습니다. 그래서 당신의 global 변수들이 여기서 초기화됩니다.

참고 (Macintosh 전용):: 애드온은 자체적으로 공유 라이브러리이므로 global 변수 사용에 제한이 없습니다.

애드온의 생애는 FreeData 함수를 호출할 때 끝납니다. 마지막에 열린 파일에서 CLOSE 커맨드가 인터프리트 되거나 ArchiCAD가 종료되면, ArchiCAD가 FreeData 함수를 호출합니다. 당신은 이 함수에서 동적으로 할당된 데이터를 해제해야 합니다. 애드온이 종료되기 전에 당신이 하고자 하는 액션들도 이때 수행해야 합니다.

요구되는 함수들

이번 섹션은 ArchiCAD 애드온을 개발하는 동안 당신의 소스 파일들에 코드화되어야 하는 함수들에 대한 자세한 설명을 제공합니다.

당신은 기능에 따라 그룹화된 이 함수들을 충족하게 될 것입니다.

라이브러리는 ArchiCAD의 요청들을 처리하는 dispatcher를 포함하고 있습니다. 이 unit은 당신의 소스 파일들에 반드시 코드화되어야 하는 당신의 함수들을 호출합니다. 이 함수들의 프로토타입들은 패키지의 일부 헤더 파일 안에 주어집니다.

	Initialize
	OpenDataFile
	InputFromDataFile
	OutputToDataFile
	CloseDataFile
	FreeData

통신 채널들을 설정하는 동안 오류가 발생하지 않는다면 ArchiCAD가 Initialize 함수를 호출합니다. 당신의 코드의 메인 엔트리 포인트로서 이 함수를 사용할 수 있습니다. 그래서 다중 I/O 채널들을 다루기 위한 필수 초기화들을 여기서 할 수 있습니다.

OPEN 또는 INITADDONSCOPE GDL 커맨드가 이 애드온에, 그리고 어떤 파일이 먼저 인터프리트 되면 OpenDataFile이 호출됩니다. 커맨드의 filter 파라미터가 애드온의 ACNF 리소스 안에 지정된 모듈 이름과 동일하면 애드온이 로드됩니다. filename과 paramstring 파라미터들이 애드온에 전달됩니다.

INPUT 또는 CALLFUNCTION GDL 커맨드가 인터프리트 될 때 InputFromDataFile이 호출됩니다. 이것은 파일로부터 값들을 읽어옵니다.

OUTPUT 또는 PREPAREFUNCTION GDL 커맨드가 인터프리트 될 때 OutputToDataFile이 호출됩니다. 이것은 파일에 nrvals 값들을 기록합니다.

만약 특수한 methodflag, keepAsOpened가 애드온의 ACNF 리소스 안에 지정되지 않았다면, (ACNF 리소스 설명은 나중에 나옴) CLOSE or CLOSEADDONSCOPE GDL 커맨드가 인터프리트 되거나 열린 파일들에 대한 인터프리트가 모두 끝날 때 CloseDataFile이 호출됩니다. 이것은 파일을 닫습니다.

애드온이 언로드되기 전에 ArchiCAD가 FreeData 함수를 호출합니다. 이것은 마지막 파일이 닫히거나 ArchiCAD가 종료할 때 발생합니다. 당신은 이 함수에서 동적으로 할당한 데이터를 해제해야 합니다. 애드온이 종료되기 전에 당신이 하고자 하는 액션들도 이때 수행해야 합니다.

리소스들

Some very important rules must be followed by anyone developing an add-on for ArchiCAD. (You will find them fulfilled by the provided example resource file that needs just really a few changes.) ArchiCAD를 위한 애드온을 개발하는 사람은 반드시 몇 가지 매우 중요한 규칙들을 따라야 합니다. (몇 가지 변경 사항만 필요로 하는 제공된 예제 리소스 파일에 의해 충족되는 그것들을 찾게 될 것입니다)

'ACNF'(32500) (GDLExtDefs.h) 리소스는 애드온의 리소스 fork 안에 포함되어야 하는 ArchiCAD를 위한 정보 소스입니다. 그것의 존재는 공유 라이브러리(Windows의 DLL)가 ArchiCAD의 유효한 애드온으로 간주되는 조건 중 하나입니다.

Macintosh의 경우:

type 'ACNF' (32500) {
	longint	= ACNFVersion;		/* reserved */
	longint	= PlatformCode;
	longint	= 0;			/* reserved */
	longint	= IoGDLMethod;		/* reserved */
	int	= Vers_IoGDLMethod;	/* reserved */
	int	= 0;			/* reserved */
	longint;			/* methodFlags */
	longint	= 0;			/* reserved */
	longint	= 0;			/* reserved */
	longint	= 0;			/* reserved */
	longint	= methodFlags;
	cstring[32];			/* module name */
};

필드 이름	필드 설명
`ACNFVersion`	ACNF 리소스의 버전 코드. 상수 값, 당신은 이것을 수정해서는 안 됩니다.
`PlatformCode`	애드온에 의해 지원되는 플랫폼을 지정합니다. `Rez` 컴파일러에 지정된 정의에 따라 VCNF.r 파일로부터 값을 가져옵니다.
`IoGDLMethod`	애드온의 메서드 코드. 상수 값, 당신은 이것을 수정해서는 안 됩니다.
`Vers_IoGDLMethod`	지원 라이브러리의 버전 코드. 상수 값, 당신은 이것을 수정해서는 안 됩니다.
`methodFlags`	애드온의 기능을 정의하는 flag. `KeepAsOpened` 만약 이것을 지정하면, ArchiCAD는 GDL 스크립트의 인터프리트가 끝날 때 열려 있는 파일(채널)들을 자동으로 닫지 않습니다. 그리고 애드온 역시 언로드되지 않습니다.\ `DeterministicResult` 만약 이것을 지정하면, 파라미터들이 바뀌지 않는 동안 애드온이 다시 호출되지 않습니다; 그 결과가 어떤 외부 데이터 소스에 의존하지 않는 경우, 결정적 결과들을 리턴하는 당신의 애드온을 마크(mark)해야 합니다. `PersistentFunction` 만약 이것을 지정하면, ArchiCAD는 애드온을 자동으로 언로드하지 않습니다. 그러나 GDL 스크립트의 인터프리트가 끝나면 열린 채널들은 닫게 됩니다. 아래의 코드 조각에 나온 대로, 당신은 세트하고 싶은 flag 값들을 합칠 수 있습니다: @#define PolyOperations_Flags DeterministicResult + PersistentFunction
`cstring[32]`	GDL에서 파일 열기 커맨드에서 식별하기 위해 애드온의 이름이 사용됩니다.

Windows의 경우:

32500	ACNF
BEGIN
	size,			/* size of ACNF - 4 (4 bytes) */
	ACNF_VERSION,		/* ACNF version     (4 bytes) */
	ACNF_PLATFORM,		/* platform code    (4 bytes) */
	0L,			/* reserved         (4 bytes) */
	IoGDLMethod,		/* method           (4 bytes) */
	Vers_IoGDLMethod,	/* methodVers       (2 bytes) */
	0,			/* reserved         (2 bytes) */
	0L,			/* methodFlags      (4 bytes) */
	"date",			/* reserved         (4 bytes) */
	"offs",			/* reserved         (4 bytes) */
	"slen",			/* reserved         (4 bytes) */
	0L,			/* reserved         (4 bytes) */
	cstring[32];		/* modul name       (32 bytes) */
END

오류 처리하기

이 메커니즘은 당신의 관점에서 매우 간단합니다.

만약 당신이 함수를 실행하는 도중 오류 조건을 조우한다면, 당신은 오류 코드를 리턴해야 합니다.

이 경우, ArchiCAD는 GDL 스크립트의 인터프리트를 중단하게 됩니다. 특수 오류 또는 경고 메시지는 확장에 의해 처리될 필요가 있습니다. 그리고 ACGD_WriteError 또는 AC_WriteReport 라이브러리 함수들을 (ACGDinc.h) 사용하여 오류나 경고를 표시해야 합니다. 이러한 함수들은 다른 GDL 오류 메시지와 마찬가지로 다이얼로그 박스에 메시지를 표시할 수 있습니다.

오류가 발생한 경우 ArchiCAD는 CloseDataFile flag가 지정되지 않은 경우 CloseDataFile을 호출하여 모든 열린 파일을 닫습니다. 마지막 열린 파일을 닫을 때 FreeData 함수가 호출됩니다.

중요: 절대로 ExitToShell 함수를 사용해서는 안 됩니다.
애드온은 반드시 ArchiCAD에 의해 종료되어야 합니다. 만약 다른 식으로 종료되면 통신 채널들은 제대로 닫히지 않게 됩니다.

패키지 구조

ArchiCAD 애드온을 개발한다는 것은 위의 요구사항들을 충족하는 공유 라이브러리를 작성한다는 것을 의미합니다. 이 코드는 동봉된 인터페이스들을 이용하여 C 언어로만 개발될 수 있습니다.

패키지 안에는 ReportGD.cpp라는 소스 코드를 포함한 예제가 있습니다. 이 예제는 ArchiCAD Report 창에 실제 GDL 커맨드의 이름과 파라미터들을 기록합니다.

만약 이 문서를 이해하는데 문제가 있다면 C 코드를 분석해 보십시오.

소스 단위	설명
GDLDev.lib/libGDLDev.a:	Win/MacTel 라이브러리는 반드시 애드온이 링크되어야 합니다.
ACGDinc.h:	애드온을 만들기 위한 필수 상수들, 타입 정의들, 함수 프로토타입들을 포함하는 C 헤더 파일입니다. 이 파일은 모든 애드온 타입들에 대하여 플랫폼 독립적이고 공통입니다.
GDLExtDefs.h:	ACNF 리소스에 의해 사용되는 상수들을 정의하는 C 헤더 파일입니다.
FileDef.h:	라이브러리 함수들에 의해 사용되는 플랫폼 의존적인 파일 정의 레코드 사양을 포함하는 C 헤더 파일입니다.
Coord3D.h TRANMAT.h GDLProc.h:	GDL 타입 정의들과 콜백 함수 프로토타입들을 포함하는 C 헤더 파일들입니다.
GDLExport.h:	GDL 모듈로부터 함수 Export의 상수들을 정의하는 C 헤더 파일입니다.
MergeNum.h:	라이브러리 릴리즈 식별 번호를 포함하는 C 헤더 파일입니다. 이것은 애드온 버전 문자열 안에 포함될 수 있습니다. (예제를 보세요)
_ACGDinc.r:	애드온 패밀리의 아이콘의 정의는 애드온에 포함되어야 합니다. (Macintosh 전용)
ResTmpl.r:	당신이 사용해야 하는 리소스들의 템플릿들을 포함합니다. ('ACNF', 'OWND', ...) (Macintosh 전용)
ACGD.ICO:	아이콘 리소스 파일 (Windows 전용)
GSRoot:	Graphisoft의 기본 모듈입니다. 기본 메모리 핸들러, 배열 핸들러, 문자열 및 문자 핸들러와 기타 유용한 함수들을 포함합니다.
GSUtils:	Graphisoft의 기본 모듈입니다. 문자열 리소스와 오류 핸들러 함수들을 포함합니다.
DGLib:	Graphisoft의 리소스와 Dialog Manager입니다. Graphisoft는 주로 Dialog/Alert 처리와 관련된 플랫폼 독립적인 다이얼로그 매니저의 기술을 가지고 있습니다. 만약 당신의 애드온에서 다이얼로그와 경고를 사용하려면 이 API를 의존하는 것을 매우 권장합니다. Graphisoft는 또한 다중 플랫폼 리소스 포맷(GRC라고 함)을 가지고 있어서, 두 플랫폼에서 공유 리소스 파일(.grc)을 사용할 수 있다.
Geometry:	Graphisoft의 기본 기하 모듈입니다. 기하 요소들과 관련 연산자들을 정의합니다.
InputOutput:	상호작용 없는 입-출력 지원입니다. 파일 시스템, 데이터 소스, 데이터 목적지, 프로토콜들이 있습니다.

ResConv.exe 유틸리티는 Windows를 위한 리소스 컴파일러입니다. 이것은 .grc 파일들을 .rc2 Windows 리소스 파일들로 컴파일합니다.
ResConv 도구는 Macintosh를 위한 리소스 컴파일러입니다. 당신은 이 도구를 사용하여 .grc 파일들을 .r Macintosh 리소스 파일들로 컴파일해야 합니다.

'GDLDev.lib' 라이브러리는 다음 기능들을 수행합니다:

공유 라이브러리의 메인 엔트리와 종료 지점(Windows의 DLL 엔트리 지점)을 포함합니다.
ArchiCAD와 애드온 간의 통신 프로세스를 처리하는 데 필요한 모든 코드를 포함합니다.
ArchiCAD 요청을 처리하는 데 도움이 되는 몇 가지 유용한 함수들을 포함합니다. 이러한 함수들은 ACGDinc.h 헤더 파일에 문서화되어 있습니다. 라이브러리에서 지원하는 모든 함수는 'ACGD_' 또는 'AC_' 접두사로 시작한다. 함수들은 다음과 같은 범주로 그룹화됩니다:
- 시스템별 지원
- 진행 바 / 리포트 처리 함수들
- 다이얼로그 박스 / 경고 처리 함수들
ArchiCAD의 요청을 처리할 dispatcher를 포함합니다. 이 unit은 소스 파일들에 코드화되어야 하는 여러 특수 함수들을 호출합니다. 이러한 함수들의 프로토타입은 ACGDinc.h 헤더 파일에 제공됩니다.
실제로 해당 함수와 함께 작업하지 않더라도 위의 함수들을 코드화하지 않으면 링커 오류가 발생할 것입니다.
이 함수 집합은 요구되는 함수들로 언급될 것입니다.

참고:

이 문서를 공부하는 동안 알 수 없는 상수 또는 structure에 대한 참조에 조우하는 경우 헤더 파일들을 참조하십시오.

서드파티 개발자들에 대한 우리의 지원은 MacTel(Mac)의 Xcode와 Windows의 Microsoft Visual C/C++에 기반을 두고 있습니다.

환경을 설정하려면 이 파일들을 하드 디스크에 복사하십시오. 우리는 또한 두 플랫폼 모두에서 예제들을 구축하기 위한 프로젝트 파일들을 제공합니다.

이 주제에 대한 자세한 정보를 원하시면 연락 바랍니다:

Graphisoft SE (Developer, international inquiries)
Graphisoft Park 1 (Záhony u.), 1031 Budapest, Hungary
Fax: (36.1) 437-3099
E-mail: GDL-Support@graphisoft.hu