XDspSubmitCommandWithEnvelope
지정된 XDSP 스트림에 대해 하드웨어 큐에 하나의 명령을 제출합니다. 이 API는 하나의 명령을 하드웨어에 제출한다는 점에서 XDspSubmitCommand와 유사하지만, 임펄스 응답 필터의 각 블록에 대한 게인 값을 포함하는 추가 매개 변수 envelopeBuffer를 사용한다는 점이 다릅니다. 이러한 게인 값은 컨볼루션 중에 임펄스 응답에 적용됩니다.엔벨로프의 사용이 필요할 때는 엔벨로프 버퍼에 대한 유효한 포인터로 이 API를 호출해야 합니다. 엔벨로프 버퍼가 더 이상 필요하지 않을 때까지 유효한 상태로 유지되도록 하는 것은 호출자의 책임입니다. 엔벨로프 사용을 중단하려면, envelopeBuffer에 nullptr를 사용하여 XDspSubmitCommand 또는 XDspSubmitCommandWithEnvelope를 호출해야 합니다. 이 API는 XDspProcessType::Convolution으로 활성화된 스트림에만 사용해야 합니다.
구문
매개 변수
handle _In_형식: XDspStreamHandle 유효한 XDSP 스트림 핸들입니다. command _In_
형식: XDspCommand* XDspCommand 구조체에 대한 포인터입니다. envelopeBuffer _In_
형식: float* 컨볼루션 중에 적용될 임펄스 응답 필터의 각 블록에 대한 게인 값에 대한 포인터입니다.
이 버퍼는 XDspConnect 또는 XDspConnectWithMaximumStreamLimit에서 등록된 메모리의 일부여야 하며 16바이트 정렬이어야 합니다. 이 버퍼는 하드웨어에서 사용되며 이 버퍼를 사용하는 모든 명령이 완료되고 응답을 수신할 때까지 수정하거나 해제할 수 없습니다. 엔벨로프 버퍼의 게인 값 개수는 임펄스 응답 필터의 블록 수 이상이어야 하며 다음과 같이 계산됩니다.
uint32_t IRLengthInComplexValues = XDspActivationParameters::impulseResponseLengthInFloats/2;
uint32_t IRLengthInBlocks = IRLengthInComplexValues/ XDspActivationParameters::blockFrameCount;
uint32_t envelopeSize = ((IRLengthInBlocks * sizeof(float) + 15) & ~(0xF)) / sizeof(float); 이 버퍼는 임펄스 응답의 크기를 따릅니다. 스테레오 임펄스 응답의 경우, 왼쪽 채널 임펄스 응답이 오른쪽 채널 임펄스 응답으로 뒤따르는 것과 동일한 방식으로 왼쪽 채널 전체에 대한 게인 값이 오른쪽 채널 전체에 대한 게인 값으로 뒤따릅니다. 모노 임펄스 응답의 경우, 스테레오 입력 신호의 왼쪽 및 오른쪽 채널 모두에 동일한 게인 값이 적용됩니다. 이 버퍼의 최소 크기는 모노 임펄스 응답 필터의 경우 8개의 float 값이어야 하며 스테레오 임펄스 응답 필터의 경우 16개의 float 값이어야 합니다. commandSequence _Out_
형식: uint32_t* 명령 시퀀스 값을 반환하기 위한
uint32_t에 대한 포인터입니다. 자세한 내용은 설명 섹션을 참조하세요.
반환 값
형식: HRESULT 메서드가 성공하면 S_OK를 반환합니다. 메서드가 실패하면 다음 코드를 반환합니다(부분 목록).설명
이 호출은 리소스를 할당하거나 데이터를 처리하지 않고 명령을 하드웨어 서버에 전송만 하므로 빠릅니다. 컨볼루션 프로세스에는 *‘n’*개의 단계가 있으며, 엔벨로핑은 첫 번째 단계에서만 켜고 끄고 전환할 수 있습니다. 즉, 엔벨로핑 효과는 즉각적이지 않을 수 있으며 몇 번의 제출로 지연될 수 있습니다. 엔벨로프 매개 변수를 사용하지 않도록 하려면, null envelopeBuffer로 XDspSubmitCommand 또는 XDspSubmitCommandWithEnvelope를 호출해야 합니다. 이 호출은 나중에 명령 결과가 준비된 시기를 추적하기 위해 명령 시퀀스 값 commandSequence를 반환하는uint32_t에 대한 포인터도 받습니다. 이 숫자는 세션 시작 이후 XDspActivate가 호출된 후 성공적으로 제출된 명령의 총 개수를 나타냅니다. 이 숫자는 첫 번째 명령의 경우 1이며 이후 성공적인 XDspSubmitCommandWithEnvelope 또는 XDspSubmitCommand 호출마다 1씩 증가합니다.
하드웨어 서버가 잘못된 상태이면 XDspSubmitCommandWithEnvelope는 XDSP_E_DEVICE_FATAL_ERROR 오류 코드를 반환합니다. 이 시점에서는 실패 상태에 있는 XDSP 스트림에 대해 더 이상 명령을 제출할 수 없습니다. 스트림의 XDspStatus도 동일한 오류를 나타냅니다. 영향을 받는 XDSP 스트림은 XDspStatus를 확인하여 제출된 모든 명령이 하드웨어에서 처리되기를 기다려야 하며, 모든 명령이 처리된 후 XDspDeactivate를 사용하여 비활성화해야 합니다. 다른 XDSP 스트림은 영향을 받지 않으며 하드웨어는 계속해서 명령을 처리합니다.
요구 사항
헤더: XDspAudio.h 라이브러리: Chad.lib 지원 플랫폼: XBOX Series X|S개념 설명서
관련 항목
XDSPXdspSubmitCommand
XDSP 오류
XDSP API를 사용한 단일 스트림 컨볼루션 개요
XDSP API를 사용한 엔벨로프 포함 단일 스트림 컨볼루션 개요 XDSP API를 사용한 단일 스트림 FFT/IFFT 개요