Graphisoft®

API Development KitVersion: 18

라이브러리 파트 개요

 

라이브러리 파트들은 기본 ArchiCAD 라이브러리와 같은 라이브러리 폴더로 수집됩니다. 활성 라이브러리 폴더 자체를 조작할 수 있습니다. ACAPI_Environment 함수를 사용하면 당신은 설치된 라이브러리들을 리셋하거나 새 폴더를 추가하거나 폴더의 전체 목록을 제공할 수도 있습니다.

ArchiCAD 8부터 라이브러리들은 아카이브 파일 및 모듈 리소스에서도 로드하거나, 역으로 패키지화 할 수 있습니다. 이 기능을 통해 애드온들은 라이브러리 파트를 자체 리소스에 저장하고, 그것들을 활성 라이브러리에 추가된 읽기 전용 라이브러리로 사용할 수 있습니다. (ACAPI_Register_BuiltInLibrary)

라이브러리 파트에 대한 참조

활성 라이브러리 폴더들이 열거되고 라이브러리 파트 파일들이 ArchiCAD에 등록됩니다. 라이브러리 파트 관리자 함수들은 등록된 라이브러리 파트에서만 작동할 수 있습니다.

라이브러리 파트를 참조해야 하는 도면 요소들(객체, 문, 창, 램프 및 구역 정의)은 인덱스로 수행합니다. 이 인덱스는 모든 활성 라이브러리에서 파트들을 포함하는 라이브러리 파트 풀의 라이브러리 파트의 인덱스입니다.

라이브러리 파트 타입

ArchiCAD 8까지 적용 가능한 라이브러리 파트의 타입들은 API_LibTypeID structure에 열거되어 있습니다. ArchiCAD 8부터 새로운 종류의 라이브러리 파트 계층이 도입되었습니다: 모든 라이브러리 파트는 서브타입 부모 라이브러리 파트로부터 파생됩니다 이 트리 구조는 라이브러리 파트들의 훨씬 더 유연한 분류를 제공해 줍니다. 자세한 설명은 라이브러리 파트 서브타입 섹션을 보십시오.

라이브러리 파트의 정의는 API_LibPart structure에 설명되어 있습니다.

어떤 종류의 라이브러리 파트들은 ArchiCAD 특정 정보가 포함되어 있지 않습니다. 예를 들면, 매크로는 간단한 텍스트 파일이고, 그림은 표준 TIFF, GIF 파일 등입니다. 그것들은 활성 라이브러리 폴더에 있다는 이유로 라이브러리 파트가 됩니다. 그것들의 콘텐츠 작업에 지원을 제공하는 API 함수들은 없습니다.

내부 구조

실제 라이브러리 파트는 ArchiCAD의 라이브러리 파트 다이얼로그에서 볼 수 있듯이 여러 섹션으로부터 만들어집니다. 각 섹션에는 API_LibPartSection structure에서 볼 수 있는 것과 같이 매우 동일한 유형으로 2개 이상의 섹션 구현을 허용하는 식별자 및 서브 코드가 있습니다.

sectType 필드는 4 바이트 코드로 구현되는 섹션의 식별자입니다. 미리 정의된 식별자도 나열되며, ArchiCAD는 이 섹션들에서만 작업할 수 있습니다. 물론 커스텀 식별자들이 있는 섹션들을 삽입하여 당신의 데이터를 라이브러리 파트에 저장할 수 있습니다. ArchiCAD는 커스텀 섹션들을 수정하거나 삭제하지 않습니다.

subIdent 필드는 서브 식별자를 제공합니다. 3D 바이너리 섹션과 같이 동일한 라이브러리 파트에 더 많은 인스턴스를 가질 수 있는 섹션들이 있습니다. 하나의 인스턴스만 가질 수 있는 섹션들은 항상 값 0을 가지고 있습니다. 커스텀 섹션들의 경우, 이 값은 유효성을 확인하지 않으며 버전 제어와 같은 아무 목적으로 사용할 수 있습니다.

라이브러리 파트와 관련된 API 함수들은 무에서부터 새로운 라이브러리 파트를 구축하는 데 필요한 모든 지원을 제공하며 기존 라이브러리 파트의 섹션을 수정, 삭제 또는 추가할 수 있는 가능성을 제공합니다. 만약 새로운 라이브러리 파트를 작성하는 경우, 해당 라이브러리는 내부 데이터베이스에 자동으로 등록되므로 모든 요소에서 참조할 수 있습니다. 자세한 내용은 ACAPI_LibPart_Create 함수를 참조하십시오.

API 함수들은 라이브러리 파트의 내부 structure를 숨기지만, 이러한 주제에 대해 이용할 수 있는 몇 가지 공개 문서가 있어서 당신 스스로 라이브러리 파트를 만들 수 있습니다. 호환성 문제로 인해 API 함수들을 사용하는 것을 적극 권장합니다.

2D 스크립트, 3D 스크립트 또는 프로퍼티 스크립트 등과 같은 텍스트 섹션들은 아무 문제없이 생성될 수 있습니다. 필요한 텍스트를 담을 수 있는 메모리를 할당하면 됩니다. API 11부터 이 섹션들은 유니코드 텍스트가 포함되어 있으며, API를 통해 조작할 수도 있습니다.

3D 바이너리 또는 2D 도면 섹션과 같은 바이너리 섹션들을 생성하거나 해석하는 것은 관리하기가 더 복잡합니다. 당신에게 그것들을 다루는 2가지 방법이 있습니다.

라이브러리 파트의 섹션 목록은 ACAPI_LibPart_GetSectionList 함수로 얻을 수 있습니다.

어떤 섹션의 데이터에 관심이 있는 경우, ACAPI_LibPart_GetSection 함수를 호출하면 쉽게 얻을 수 있습니다. 바이너리 섹션의 경우, API structure에 대응하지 않는 바이너리 데이터를 얻을 수 있습니다. 텍스트 섹션의 경우, 리턴된 sectionHdl이 필요한 텍스트를 포함하고 있습니다.

2D 도면 섹션

2D 도면 섹션은 적용할 수 있는 2D 툴바 요소들로 그릴 수 있는 라이브러리 파트의 형태를 설명합니다.

이 때 API 형태로 이 데이터를 얻을 수 있는 유일한 방법은 ACAPI_LibPart_ShapePrims 함수를 사용하는 것입니다. 이 함수 호출은 라이브러리 파트의 형태를 드로잉 primitive들로 분해합니다.

이 바이너리 섹션을 만들려면, 요소 작성 절차를 리디렉션해야 합니다. 이 경우, ACAPI_Element_Create 함수에 대한 후속 호출들은 프로젝트 데이터베이스 대신 주어진 요소들을 임시 풀에 배치합니다. 당신이 도면 작성 절차를 완료하면 이 요소들을 필요한 바이너리 형태로 변환할 수 있습니다.

GSHandle            bin2DHdl;
API_SelectionInfo   section;
GSErrCode           err;

err = ACAPI_LibPart_SetUpSect_2DDrawHdl ();
ACAPI_Element_Create()
...
ACAPI_Element_Create()
err = ACAPI_LibPart_GetSect_2DDrawHdl (&bin2DHdl);

BNZeroMemory (&section, sizeof (API_LibPartSection));
section.sectType = API_Sect2DDraw;
err = ACAPI_LibPart_AddSection (&section, bin2DHdl, NULL);

BMKillHandle (&bin2DHdl);

파라미터 섹션

파라미터 섹션에서는 라이브러리 파트의 기본 파라미터를 설명합니다.

모든 실제 라이브러리 파트에는 미리 정의된 2개의 파라미터가 있습니다; A와 B. 다른 종류의 라이브러리 파트들은 추가로 요구되는 파라미터가 포함될 수 있습니다. ArchiCAD에 그런 종류의 새로운 라이브러리 파트를 만들어서 이것들을 확인할 수 있습니다. 다이얼로그에 나타나는 파라미터들은 필수 파라미터입니다. 이 외에도 추가 파라미터를 정의하거나 가져올 수 있습니다. (최대 64개) 파라미터 조작 함수들은 모두 이러한 추가(필수 그리고/또는 선택적) 파라미터들을 참조하지만, 필요한 경우 별도의 파라미터들인 A와 B 파라미터는 참조하지 않습니다.

적용 가능한 추가 파라미터 타입들이 API_AddParID structure에 열거되어 있습니다. 추가 파라미터의 정의는 API_AddParType structure에 설명되어 있습니다:

만약 당신이 API 기반 형태에서 라이브러리 파트의 파라미터 목록을 얻으려면 다음 템플릿을 사용해야 합니다:

Int32            addParNum;
API_AddParType   addParHdl;
double           a, b;

err = ACAPI_LibPart_GetParams (libIndex, &a, &b, &addParNum, &addParHdl);

 

이 경우 ArchiCAD는 바이너리 데이터를 API_AddParType structure의 배열로 변환합니다. addParHdl에 추가 파라미터들만 포함되기 때문에 이 함수는 별도의 변수에서 a와 b 파라미터를 리턴합니다.

파라미터 섹션의 생성도 매우 간단합니다. 먼저 API_AddParType structure를 기반으로 필요한 배열 크기를 할당하고 파라미터의 데이터를 채워야 합니다. 다음 단계에서는 이 API 데이터를 바이너리 데이터로 변환해야 합니다. 그러기 위해서는 2D 바이너리 섹션 데이터도 필요합니다. 왜냐하면 바이너리 파라미터 핸들은 a와 b 파라미터를 소유하는 전체 설명이기 때문입니다. 이러한 파라미터들은 자동으로 계산되고, 구축된 바이너리 섹션은 paramsHdl 인수를 통해 당신에게 리턴됩니다. 당신은 또한 계산된 a와 b 파라미터도 가져오게 됩니다.

GSHandle            paramsHdl;
API_SelectionInfo   section;
GSErrCode           err;

err = ACAPI_LibPart_GetSect_ParamDef (APILib_ObjectID, addParHdl,
                                      &a, &b, bin2DHdl,
                                      &paramsHdl);

BNZeroMemory (&section, sizeof (API_LibPartSection));
section.sectType = API_SectParamDef;
err = ACAPI_LibPart_AddSection (&section, paramsHdl, NULL);

BMKillHandle (&paramsHdl);

3D 바이너리 섹션

API의 현재 버전에서는 3D 바이너리 섹션의 내부 데이터를 처리할 수 있는 지원이 없습니다. 만약 당신이 이 섹션에서 작업하고 싶다면 Graphisoft에 연락하여 바이너리 포맷에 필요한 문서를 가져오십시오.

라이브러리 파트는 2개 이상의 3D 바이너리 섹션을 최대 16개의 조각까지 소유할 수 있습니다. 올바른 조각을 얻으려면 API_LibPartSection structure의 subIdent 필드를 올바르게 세트해야 합니다.

미리보기 그림

미리보기 그림은 PICT 또는 GIF 포맷으로 라이브러리 파트에 내장할 수 있습니다. 그것들은 공공 포맷이기 때문에 아무런 설명도 필요하지 않습니다.