KSPROPSETID_Synth_Dls

속성 집합에는 KSPROPSETID_Synth_Dls MIDI 신시사이저에 DLS 샘플 및 계측을 다운로드하는 데 사용되는 속성이 포함되어 있습니다. DirectMusic 필터의 DirectMusic 핀에 있는 신디 노드(KSNODETYPE_SYNTHESIZER)의 속성입니다( MIDI 및 DirectMusic 필터 참조).

이 섹션에서는 DLS 데이터가 포함된 메모리의 "청크"를 다운로드하고 언로드하는 방법과 관련하여 이러한 속성의 동작에 대해 설명합니다. 다운로드한 계측 및 웨이브 데이터 청크의 실제 형식은 Microsoft Windows SDK 설명서의 하위 수준 DLS 설명서에 지정되어 있습니다.

DLS 다운로드 및 언로드는 핀이 있는 동안 언제든지 발생할 수 있습니다. DirectMusic 이벤트와 달리 타임스탬프는 지정되지 않으며 가능한 한 빨리 처리해야 합니다.

이 섹션에서는 DLS 리소스 또는 리소스라는 용어는 DLS 계측 청크 또는 DLS 웨이브 청크를 나타냅니다. 시스템은 모든 DLS 리소스에 대한 참조 수를 올바르게 유지 관리합니다.

• 클라이언트가 웨이브를 참조하는 마지막 계측을 언로드하면 시스템에서 웨이브를 언로드하는 호출을 자동으로 생성합니다.

• 반대로, 시스템은 클라이언트가 웨이브를 참조하는 마지막 계측을 언로드할 때까지 웨이브를 언로드하는 호출을 연기합니다.

이 집합의 속성 항목은 헤더 파일 Dmusprop.h에 정의된 대로 KSPROPERTY_SYNTH_DLS 열거형 값으로 지정됩니다.

사용 요약 테이블

KSPROPERTY_SYNTH_DLS_APPEND 속성은 클라이언트가 신시사이저에 다운로드하는 각 버퍼의 DLS 데이터에 추가하는 예약된 스토리지 공간의 크기를 지정합니다.

속성 값(작업 데이터)은 ULONG 형식이며 미니포트 드라이버가 다운로드한 각 DLS 데이터 버퍼의 끝에서 자체 사용을 위해 예약해야 하는 바이트 수를 지정합니다. 그런 다음, 클라이언트는 다운로드한 데이터가 종료된 후 요청된 바이트 수를 포함할 수 있을 만큼 충분히 커지도록 각 다운로드 버퍼를 할당합니다.

반환 값

KSPROPERTY_SYNTH_DLS_APPEND 속성 요청은 성공적으로 완료되었음을 나타내는 STATUS_SUCCESS 반환합니다. 그렇지 않으면 요청이 적절한 오류 상태 코드를 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

이러한 추가 바이트는 맞춤 요구 사항을 위해 추가 패딩이 필요하거나 샘플 보간을 간소화하기 위해 샘플의 시작을 복제하는 드라이버를 위한 것입니다.

사용 요약 테이블

KSPROPERTY_SYNTH_DLS_COMPACT 속성은 가능한 가장 큰 사용 가능한 샘플 메모리 청크를 사용할 수 있도록 신시사이저에 대한 요청입니다.

이 속성과 연결된 속성 값(작업 데이터)이 없습니다.

반환 값

KSPROPERTY_SYNTH_DLS_COMPACT 속성 요청은 성공적으로 완료되었음을 나타내는 STATUS_SUCCESS 반환합니다. 그렇지 않으면 요청이 적절한 오류 상태 코드를 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

이 속성에 대한 처리기의 구현은 재생을 중단해서는 안 됩니다.

자세한 내용은 Microsoft Windows SDK 설명서의 IDirectMusicPort::Compact 메서드에 대한 설명을 참조하세요.

사용 요약 테이블

KSPROPERTY_SYNTH_DLS_DOWNLOAD 속성은 Synthesizer에 DLS 데이터를 다운로드하는 데 사용됩니다.

속성 설명자(instance 데이터)는 다운로드되는 DLS 데이터 버퍼의 위치와 크기를 지정하는 SYNTH_BUFFER 구조가 바로 뒤에 있는 KSNODEPROPERTY 구조로 구성됩니다.

속성 값(작업 데이터)은 SYNTHDOWNLOAD 구조체입니다. 미니포트 드라이버는 이 구조에서 다음 정보를 다시 전달합니다.

• 미니포트 드라이버가 다운로드한 DLS 데이터를 고유하게 식별하기 위해 생성하는 핸들입니다. 이 클라이언트는 이 핸들을 저장하고 나중에 데이터를 언로드하는 데 사용해야 합니다( KSPROPERTY_SYNTH_DLS_UNLOAD 참조).

• 속성 요청이 완료된 후 클라이언트가 DLS 데이터가 포함된 버퍼를 해제할 수 있는지 여부를 나타내는 부울 값입니다. 미니포트 드라이버가 DLS 데이터의 자체 복사본을 만든 경우 클라이언트는 버퍼를 해제할 수 있습니다. 그렇지 않으면 미니포트 드라이버가 클라이언트의 원래 DLS 데이터 버퍼를 계속 사용하는 경우 미니포트 드라이버가 DLS 데이터를 언로드할 때까지 클라이언트는 버퍼를 해제하지 않아야 합니다.

반환 값

KSPROPERTY_SYNTH_DLS_DOWNLOAD 속성 요청은 성공적으로 완료되었음을 나타내는 STATUS_SUCCESS 반환합니다. 그렇지 않으면 요청이 적절한 오류 상태 코드를 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

자세한 내용은 Microsoft Windows SDK 설명서에서 IDirectMusicPort::D ownloadInstrument 메서드에 대한 설명을 참조하세요.

예제

KSPROPERTY_SYNTH_DLS_DOWNLOAD 속성 요청은 사용자 메모리 주소를 사용하여 DLS 다운로드 데이터의 위치를 지정합니다. 미니포트 드라이버는 액세스하기 전에 DLS 데이터가 포함된 사용자 메모리를 검색하고 잠가야 합니다. 다음 예제 코드는 이 작업을 수행하는 방법을 보여줍니다.

  NTSTATUS Status = STATUS_UNSUCCESSFUL;
  PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
  PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
                            FALSE, FALSE, NULL);
  if (pMdl)
  {
      __try
      {
          MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
          PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
 
         // do something with the data here
      }
      __except (EXCEPTION_EXECUTE_HANDLER)
      {
          Status = GetExceptionCode();
      }
 
      MmUnlockPages(pMdl);
      IoFreeMdl(pMdl);
  }
  else
  {
      Status = STATUS_NO_MEMORY;
  }

사용 요약 테이블

KSPROPERTY_SYNTH_DLS_UNLOAD 속성은 이전에 다운로드한 DLS 데이터 리소스를 언로드합니다.

속성 값(작업 데이터)은 HANDLE 형식이며 해제할 다운로드한 DLS 데이터 리소스의 핸들을 포함합니다. 이전 KSPROPERTY_SYNTH_DLS_DOWNLOADget-property 요청에서 DLS 데이터를 식별하기 위해 미니포트 드라이버가 생성한 핸들입니다.

반환 값

KSPROPERTY_SYNTH_DLS_UNLOAD 속성 요청은 STATUS_SUCCESS 반환하여 성공적으로 완료되었음을 나타냅니다. 그렇지 않으면 요청은 코드에 적절한 오류 상태 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

미니포트 드라이버는 DLS 데이터를 사용하는 노트가 재생되지 않는 즉시 DLS 데이터를 언로드해야 합니다. synthesizer가 KSPROPERTY_SYNTH_DLS_UNLOAD set-property 요청 시 DLS 데이터 리소스와 연결된 메모리를 해제할 수 없는 경우 비동기 속성 완성을 사용하여 나중에 요청을 완료할 수 있습니다.

DLS 데이터 리소스를 언로드한 후 신시사이저가 리소스를 사용하는 메모 표시 이벤트를 수신하는 경우 미니포트 드라이버는 중간에 새 DLS 데이터 리소스를 다운로드하지 않는 한 이벤트를 무시해야 합니다.

자세한 내용은 Microsoft Windows SDK 설명서에서 IDirectMusicPort::UnloadInstrument 메서드에 대한 설명을 참조하세요.

사용량 요약 테이블

KSPROPERTY_SYNTH_DLS_WAVEFORMAT 속성은 출력 웨이브 형식에 대한 신시사이저를 쿼리하는 데 사용됩니다.

속성 값(작업 데이터)은 WAVEFORMATEX 형식이며 신시사이저 출력 스트림의 웨이브 형식을 지정합니다.

반환 값

KSPROPERTY_SYNTH_DLS_WAVEFORMAT 속성 요청은 성공적으로 완료되었음을 나타내는 STATUS_SUCCESS 반환합니다. 그렇지 않으면 요청은 코드에 적절한 오류 상태 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

sizeof(WAVEFORMATEX) 바이트의 속성 값 버퍼는 모든 웨이브 형식에 충분히 크지 않을 수 있습니다. 예를 들어 다중 채널 형식에는 sizeof(WAVEFORMATEXTENSIBLE) 바이트의 버퍼가 필요합니다. 속성 요청이 STATUS_BUFFER_TOO_SMALL 상태 코드를 반환하는 경우 클라이언트는 미니포트 드라이버가 출력하는 속성 값 크기를 검사 더 큰 버퍼를 할당한 다음 두 번째 요청을 제출할 수 있습니다.

자세한 내용은 Microsoft Windows SDK 설명서에서 IDirectMusicPort::GetFormat 메서드에 대한 설명을 참조하세요.