GetImage 샘플: Windows 이미지 인식 API 설명
업데이트: 2007년 11월
GetImage 샘플은 WIA(Windows 이미지 인식) API(응용 프로그래밍 인터페이스)를 보여 줍니다.
WIA API 집합에는 파일 전송을 위한 간단한 API가 포함되어 있지만 메모리 내 전송을 위한 간단한 API 호출은 없습니다. GetImage는 SelectDeviceDlg, DeviceDlg 및 idtGetBandedData API의 기능을 결합하여 한 번의 함수 호출로 이미지 인식을 완전히 캡슐화하는 WiaGetImage라는 래퍼 함수를 구현합니다.
샘플의 주 기능은 코드 자체입니다. WiaWrap, EventCallback, DataCallback, BitmapUtil 및 ProgressDlg 파일은 메모리 내의 이미지 전송을 구현하기 위한 올바른 방법을 보여 줍니다. 이 요약의 뒷 부분에 나오는 "WIA API를 사용한 프로그래밍 정보" 단원에서는 WIA 응용 프로그램을 작성할 때 일반적으로 주의해야 할 사항을 강조하고 그 처리 방법을 샘플을 통해 보여 줍니다. 이러한 샘플을 참고로 읽을 수도 있고 샘플 코드를 라이브러리로 직접 사용할 수도 있습니다. 각 함수의 사용법에 대해서는 헤더 파일 설명 부분에 자세히 나와 있습니다.
.gif "보안 정보") 보안 정보: |
|---|
이 샘플 코드는 개념을 보여 주기 위해 제공되며 가장 안전한 코드 작성 방법을 제시하지 않을 수 있으므로 응용 프로그램이나 웹 사이트에서 사용할 수 없습니다. Microsoft는 샘플 코드를 원래 용도 이외의 다른 용도로 사용하는 경우 발생하는 부수적이나 파생적인 손해에 대해 책임을 지지 않습니다. |
샘플 및 이를 설치하기 위한 지침을 가져오려면
Visual Studio의 도움말 메뉴에서 샘플을 클릭합니다.
자세한 내용은 샘플 파일 찾기를 참조하십시오.
최신 버전 및 전체 샘플 목록은 Visual Studio 2008 Samples 페이지에서 온라인으로 사용할 수 있습니다.
컴퓨터의 하드 디스크에서도 샘플을 찾을 수 있습니다. 기본적으로 샘플과 추가 정보 파일은 \Program Files\Visual Studio 9.0\Samples\ 아래의 폴더에 복사됩니다. Visual Studio Express Edition의 경우에는 모든 샘플이 온라인에 있습니다.
요구 사항
이 샘플은 Windows XP 이상에서만 실행할 수 있습니다.
Microsoft Windows SDK가 설치되어 있어야 합니다.
샘플 빌드 및 실행
이 샘플을 빌드하고 실행하려면
Visual Studio에서 솔루션 GetImage.sln을 로드합니다.
솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성을 클릭한 후 다음 속성을 설정합니다.
C++ 폴더, 일반 속성 페이지: 추가 포함 디렉터리 속성을 수정하여 Windows SDK 헤더 파일이 들어 있는 디렉터리(예: c:\Microsoft Windows SDK\include)를 추가합니다.
링커 폴더, 일반 속성 페이지: 추가 라이브러리 디렉터리 속성을 수정하여 Windows SDK 라이브러리 파일이 들어 있는 디렉터리(예: c:\Microsoft Windows SDK\lib)를 추가합니다.
빌드 메뉴에서 빌드를 클릭합니다.
디버그 메뉴에서 디버깅하지 않고 시작을 클릭합니다.
샘플 응용 프로그램은 File 메뉴에 From scanner or camera라는 단일 명령을 갖습니다. WIA 장치나 장치 에뮬레이터를 연결하면 메뉴 항목이 활성화됩니다. 사용자가 메뉴 명령을 선택하면 샘플에서 WIA Device Selection 대화 상자, Image Selection 대화 상자, Image Transfer 대화 상자가 순차적으로 표시됩니다. 장치 및 이미지 선택 대화 상자는 시스템에서 제공하는 일반 대화 상자이며 전송 대화 상자는 이 샘플에서 구현됩니다. 마지막으로 샘플에서는 전송된 이미지를 자식 창에 표시합니다.
샘플의 파일
파일 |
설명 |
|---|---|
WiaWrap.cpp |
WIA 작업을 단순화하기 위한 래퍼 함수가 들어 있습니다. |
WiaWrap.h |
WiaWrap.cpp의 헤더 파일입니다. |
EventCallback.cpp |
WIA 장치 이벤트에 대한 콜백 함수를 구현합니다. |
EventCallback.h |
EventCallback.cpp의 헤더 파일입니다. |
DataCallback.cpp |
데이터 전송에 대한 콜백 함수를 구현합니다. |
DataCallback.h |
DataCallback.cpp의 헤더 파일입니다. |
BitmapUtil.cpp |
DIB(장치 독립적 비트맵) 함수가 들어 있습니다. |
BitmapUtil.h |
BitmapUtil.cpp의 헤더 파일입니다. |
ProgressDlg.cpp |
간단한 진행률 대화 상자를 구현합니다. |
ProgressDlg.h |
ProgressDlg.cpp의 헤더 파일입니다. |
GetImage.cpp |
응용 프로그램의 주 진입점을 구현합니다. |
GetImage.rc |
프로젝트 리소스가 들어 있습니다. |
resource.h |
리소스 식별자의 헤더 파일입니다. |
MainWnd.cpp |
주 프레임 창을 구현합니다. |
MainWnd.h |
MainWnd.cpp의 헤더 파일입니다. |
BitmapWnd.cpp |
이미지 표시 창을 구현합니다. |
BitmapWnd.h |
BitmapWnd.cpp의 헤더 파일입니다. |
StdAfx.cpp |
미리 컴파일된 헤더 파일입니다. |
StdAfx.h |
자주 사용하는 표준 시스템 파일이 들어 있습니다. |
WIA API를 사용한 프로그래밍 정보
응용 프로그램은 File 메뉴의 **From scanner or camera...**라는 메뉴 항목을 통해 장치와 이미지 선택을 사용할 수 있게 하는 것이 좋습니다. 시스템에 WIA 장치가 없으면 이 항목이 회색으로 표시될 수 있습니다.
응용 프로그램 개발자는 직렬 및 USB 카메라와 평판, 스크롤 피드, ADF 스캐너를 사용하여 응용 프로그램을 테스트하는 것이 좋습니다. 그리고 Windows DDK에서 사용할 수 있는 소프트웨어 전용 장치 에뮬레이터도 테스트에 사용할 수 있습니다.
스크롤 피드 스캐너는 일반적으로 데이터 전송이 시작될 때 이미지 높이를 알 수 없으므로 비트맵 헤더의 이미지 크기와 이미지 높이에 대해 0을 반환할 수 있습니다. 이러한 경우 콜백 함수는 새 데이터가 도착할 때 버퍼를 확장할 수 있어야 하며 전송이 완료되었을 때는 높이를 정확하게 계산할 수 있어야 합니다.
ADF(자동 문서 공급 장치)에서 DeviceDlg API를 사용하면 API는 한 페이지를 스캔하도록 ADF를 설정합니다. 여러 페이지를 스캔하려면 응용 프로그램에서 WIA_DPS_PAGES를 ALL_PAGES 값 또는 요청하는 페이지 수로 명시적으로 설정해야 합니다.
사용자가 취소하면 SelectDeviceDlg, DeviceDlg, idtGetData 및 idtGetBandedData API가 S_FALSE를 반환하므로, SUCCEEDED 매크로를 사용하여 반환 값을 검사하는 것만으로는 충분하지 않습니다. 프로그래머가 명시적으로 S_FALSE 값을 검사해야 합니다. 마찬가지로 함수 인수가 올바르면 ReadMultiple과 WriteMultiple API도 S_FALSE를 반환하지만 함수에서 요청한 작업을 수행할 수는 없습니다. 따라서 프로그래머가 S_FALSE에 대한 반환 값을 명시적으로 검사해야 합니다.
취소할 수 있는 진행률 대화 상자를 응용 프로그램에서 표시하려면 별도의 스레드로 이 대화 상자를 표시해야 합니다. 전송이 완료될 때까지는 데이터 전송 스레드가 차단되므로 창 메시지를 도착하는 즉시 처리할 수는 없습니다. 진행률 대화 상자를 같은 스레드에서 만들면 대화 상자와 취소 단추는 사용자 입력에 대해 속도가 매우 느려집니다.
BandedDataCallback이 반환될 때만 데이터 전송을 취소할 수 있습니다. BandedDataCallback은 몇 초 간격으로 호출될 수 있으므로 응용 프로그램은 취소 작업이 진행 중임을 사용자에게 나타내야 합니다. 예를 들면, 취소 단추를 사용할 수 없게 하거나 대기 메시지를 표시할 수 있습니다.
키워드
이 샘플에서는 다음의 키워드를 보여 줍니다.
IWiaDevMgr, IWiaDevMgr::SelectDeviceDlg, IWiaEventCallback, IWiaEventCallback::ImageEventCallback, IWiaItem, IWiaItem::DeviceDlg, IWiaPropertyStorage, IWiaPropertyStorage::ReadMultiple, IWiaPropertyStorage::WriteMultiple, IWiaDataTransfer, IWiaDataTransfer::idtGetBandedData, IWiaDataCallback, IWiaDataCallback::BandedDataCallback