- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true);
-
-
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback((string command) => Console.WriteLine(command));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true)
- .Returns(true);
-
- Note that in the case of value-returning methods, after the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback(command => Console.WriteLine(command))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15, arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var mock = new Mock<IContainer>();
-
- mock.Setup(add => add.Add(It.IsAny<string>(), It.IsAny<object>()))
- .Raises(add => add.Added += null, EventArgs.Empty);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the method
- is executed and the value the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Returns((string command) => returnValues[command]);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2) => arg1 + arg2);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3) => arg1 + arg2 + arg3);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4) => arg1 + arg2 + arg3 + arg4);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5) => arg1 + arg2 + arg3 + arg4 + arg5);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16);
-
-
- // Typed instance, not the mock, is retrieved from some test API.
- HttpContextBase context = GetMockContext();
-
- // context.Request is the typed object from the "real" API
- // so in order to add a setup to it, we need to get
- // the mock that "owns" it
- Mock<HttpRequestBase> request = Mock.Get(context.Request);
- mock.Setup(req => req.AppRelativeCurrentExecutionFilePath)
- .Returns(tempUrl);
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Verifiable().Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory.
- this.Verify();
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory, even
- // that expectation was not marked as verifiable.
- this.VerifyAll();
-
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
- // add IDisposable interface
- var disposable = mock.As<IDisposable>();
- disposable.Setup(d => d.Dispose()).Verifiable();
-
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- repository.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the repository
- to create loose mocks and later verify only verifiable setups:
-
- var repository = new MockRepository(MockBehavior.Loose);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // this setup will be verified when we verify the repository
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the repository
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- repository.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the repository with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = repository.Create<IFoo>(MockBehavior.Loose);
- var bar = repository.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- repository.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- factory.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the factory
- to create loose mocks and later verify only verifiable setups:
-
- var factory = new MockFactory(MockBehavior.Loose);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // this setup will be verified when we verify the factory
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the factory
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- factory.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the factory with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
- var bar = factory.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- // use mock on tests
-
- factory.VerifyAll();
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>("Foo", 25, true);
- // use mock on tests
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>(MockBehavior.Strict, "Foo", 25, true);
-
-
- mock.Setup(x => x.Execute(""))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.Execute(""))
- .Throws<ArgumentException>();
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMostOnce();
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMost( 5 );
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable();
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable("Ping should be executed always!");
-
-
- mock.SetupGet(x => x.Suspended)
- .Callback(() => called = true)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the property
- is retrieved and the value the
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- Note that the return value from the compiler matcher is irrelevant.
- This method will never be called, and is just used to satisfy the
- compiler and to signal Moq that this is not a method that we want
- to be invoked at runtime.
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
-
- At runtime, the mocked method will be invoked with a specific
- list of orders. This value will be passed to this runtime
- matcher as the first argument, while the second argument is the
- one specified in the setup (
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
- }
-
- And the concrete test using this matcher:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- // use mock, invoke Save, and have the matcher filter.
-
-
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- mock.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.True(order.IsFilled);
-
- The following example shows how to use the
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- // shows how to expect a value within a range
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
- // shows how to throw for unexpected calls.
- mock.Setup(x => x.Remove(
- It.IsAny<string>(),
- It.IsAny<int>()))
- .Throws(new InvalidOperationException());
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.False(order.IsFilled);
-
- var mock = new Mock<IFormatProvider>();
- var mock = new Mock<MyProvider>(someArgument, 25);
- var mock = new Mock<IFormatProvider>(MockBehavior.Relaxed);
- var mock = new Mock<MyProvider>(someArgument, 25);
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
-
- mock.Setup(x => x.HasInventory("Talisker", 50)).Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- var mock = new Mock<IHaveValue>();
- mock.Stub(v => v.Value);
-
- After the
- IHaveValue v = mock.Object;
-
- v.Value = 5;
- Assert.Equal(5, v.Value);
-
-
- var mock = new Mock<IHaveValue>();
- mock.SetupProperty(v => v.Value, 5);
-
- After the
- IHaveValue v = mock.Object;
- // Initial value was stored
- Assert.Equal(5, v.Value);
-
- // New value set which changes the initial value
- v.Value = 6;
- Assert.Equal(6, v.Value);
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50), "When filling orders, inventory has to be checked");
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true, "Warehouse should always be closed after the action");
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.PropertyChanged -= null, new PropertyChangedEventArgs("Name"));
-
-
- var mockView = new Mock<IOrdersView>();
- var presenter = new OrdersPresenter(mockView.Object);
-
- // Check that the presenter has no selection by default
- Assert.Null(presenter.SelectedOrder);
-
- // Raise the event with a specific arguments data
- mockView.Raise(v => v.SelectionChanged += null, new OrderEventArgs { Order = new Order("moq", 500) });
-
- // Now the presenter reacted to the event, and we have a selected order
- Assert.NotNull(presenter.SelectedOrder);
- Assert.Equal("moq", presenter.SelectedOrder.ProductName);
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.MyEvent -= null, "Name", bool, 25);
-
-
- mock.SetupSet(x => x.Suspended);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- mock.SetupSet(x => x.Suspended)
- .Callback((bool state) => Console.WriteLine(state));
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Setup(x => x.Remove(It.IsAny<string>())).Throws(new InvalidOperationException());
-
-
- mock.Setup(x => x.Do(It.Is<int>(i => i % 2 == 0)))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Setup(x => x.GetUser(It.Is<int>(i => i < 0)))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(1, 2, 3)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(1, 2, 3)))
- .Returns(false);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+"))).Returns(1);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+", RegexOptions.IgnoreCase))).Returns(1);
-
-
- // Throws an exception for a call to Remove with a null string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsNull<string>())
- .Throws(new InvalidOperationException());
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsAny<string>())
- .Throws(new InvalidOperationException());
-
-
- mock.Protected()
- .Setup("Do", ItExpr.Is<int>(i => i % 2 == 0))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Protected()
- .Setup("GetUser", ItExpr.Is<int>(i => i < 0))
- .Throws(new ArgumentException());
-
-
- mock.Protected()
- .Setup("HasInventory",
- ItExpr.IsAny<string>(),
- ItExpr.IsInRange(0, 100, Range.Inclusive))
- .Returns(false);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+"))
- .Returns(1);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+", RegexOptions.IgnoreCase))
- .Returns(1);
-
-
- [Matcher]
- public Order IsBigOrder()
- {
- return Match<Order>.Create(
- o => o.GrandTotal >= 5000,
- /* a friendly expression to render on failures */
- () => IsBigOrder());
- }
-
- This method can be used in any mock setup invocation:
-
- mock.Setup(m => m.Submit(IsBigOrder()).Throws<UnauthorizedAccessException>();
-
- At runtime, Moq knows that the return value was a matcher (note that the method MUST be
- annotated with the [Matcher] attribute in order to determine this) and
- evaluates your predicate with the actual value passed into your predicate.
-
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return Match<IEnumerable<Order>>.Create(orders => orders.Contains(order));
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
-
- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true);
-
-
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback((string command) => Console.WriteLine(command));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true)
- .Returns(true);
-
- Note that in the case of value-returning methods, after the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback(command => Console.WriteLine(command))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15, arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var mock = new Mock<IContainer>();
-
- mock.Setup(add => add.Add(It.IsAny<string>(), It.IsAny<object>()))
- .Raises(add => add.Added += null, EventArgs.Empty);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the method
- is executed and the value the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Returns((string command) => returnValues[command]);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2) => arg1 + arg2);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3) => arg1 + arg2 + arg3);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4) => arg1 + arg2 + arg3 + arg4);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5) => arg1 + arg2 + arg3 + arg4 + arg5);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16);
-
-
- // Typed instance, not the mock, is retrieved from some test API.
- HttpContextBase context = GetMockContext();
-
- // context.Request is the typed object from the "real" API
- // so in order to add a setup to it, we need to get
- // the mock that "owns" it
- Mock<HttpRequestBase> request = Mock.Get(context.Request);
- mock.Setup(req => req.AppRelativeCurrentExecutionFilePath)
- .Returns(tempUrl);
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Verifiable().Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory.
- this.Verify();
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory, even
- // that expectation was not marked as verifiable.
- this.VerifyAll();
-
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
- // add IDisposable interface
- var disposable = mock.As<IDisposable>();
- disposable.Setup(d => d.Dispose()).Verifiable();
-
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- repository.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the repository
- to create loose mocks and later verify only verifiable setups:
-
- var repository = new MockRepository(MockBehavior.Loose);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // this setup will be verified when we verify the repository
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the repository
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- repository.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the repository with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = repository.Create<IFoo>(MockBehavior.Loose);
- var bar = repository.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- repository.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- factory.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the factory
- to create loose mocks and later verify only verifiable setups:
-
- var factory = new MockFactory(MockBehavior.Loose);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // this setup will be verified when we verify the factory
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the factory
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- factory.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the factory with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
- var bar = factory.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- // use mock on tests
-
- factory.VerifyAll();
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>("Foo", 25, true);
- // use mock on tests
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>(MockBehavior.Strict, "Foo", 25, true);
-
-
- mock.Setup(x => x.Execute(""))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.Execute(""))
- .Throws<ArgumentException>();
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMostOnce();
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMost( 5 );
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable();
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable("Ping should be executed always!");
-
-
- mock.SetupGet(x => x.Suspended)
- .Callback(() => called = true)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the property
- is retrieved and the value the
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- Note that the return value from the compiler matcher is irrelevant.
- This method will never be called, and is just used to satisfy the
- compiler and to signal Moq that this is not a method that we want
- to be invoked at runtime.
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
-
- At runtime, the mocked method will be invoked with a specific
- list of orders. This value will be passed to this runtime
- matcher as the first argument, while the second argument is the
- one specified in the setup (
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
- }
-
- And the concrete test using this matcher:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- // use mock, invoke Save, and have the matcher filter.
-
-
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- mock.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.True(order.IsFilled);
-
- The following example shows how to use the
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- // shows how to expect a value within a range
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
- // shows how to throw for unexpected calls.
- mock.Setup(x => x.Remove(
- It.IsAny<string>(),
- It.IsAny<int>()))
- .Throws(new InvalidOperationException());
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.False(order.IsFilled);
-
- var mock = new Mock<IFormatProvider>();
- var mock = new Mock<MyProvider>(someArgument, 25);
- var mock = new Mock<IFormatProvider>(MockBehavior.Relaxed);
- var mock = new Mock<MyProvider>(someArgument, 25);
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
-
- mock.Setup(x => x.HasInventory("Talisker", 50)).Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- var mock = new Mock<IHaveValue>();
- mock.Stub(v => v.Value);
-
- After the
- IHaveValue v = mock.Object;
-
- v.Value = 5;
- Assert.Equal(5, v.Value);
-
-
- var mock = new Mock<IHaveValue>();
- mock.SetupProperty(v => v.Value, 5);
-
- After the
- IHaveValue v = mock.Object;
- // Initial value was stored
- Assert.Equal(5, v.Value);
-
- // New value set which changes the initial value
- v.Value = 6;
- Assert.Equal(6, v.Value);
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50), "When filling orders, inventory has to be checked");
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true, "Warehouse should always be closed after the action");
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.PropertyChanged -= null, new PropertyChangedEventArgs("Name"));
-
-
- var mockView = new Mock<IOrdersView>();
- var presenter = new OrdersPresenter(mockView.Object);
-
- // Check that the presenter has no selection by default
- Assert.Null(presenter.SelectedOrder);
-
- // Raise the event with a specific arguments data
- mockView.Raise(v => v.SelectionChanged += null, new OrderEventArgs { Order = new Order("moq", 500) });
-
- // Now the presenter reacted to the event, and we have a selected order
- Assert.NotNull(presenter.SelectedOrder);
- Assert.Equal("moq", presenter.SelectedOrder.ProductName);
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.MyEvent -= null, "Name", bool, 25);
-
-
- mock.SetupSet(x => x.Suspended);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- mock.SetupSet(x => x.Suspended)
- .Callback((bool state) => Console.WriteLine(state));
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Setup(x => x.Remove(It.IsAny<string>())).Throws(new InvalidOperationException());
-
-
- mock.Setup(x => x.Do(It.Is<int>(i => i % 2 == 0)))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Setup(x => x.GetUser(It.Is<int>(i => i < 0)))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(1, 2, 3)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(1, 2, 3)))
- .Returns(false);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+"))).Returns(1);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+", RegexOptions.IgnoreCase))).Returns(1);
-
-
- // Throws an exception for a call to Remove with a null string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsNull<string>())
- .Throws(new InvalidOperationException());
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsAny<string>())
- .Throws(new InvalidOperationException());
-
-
- mock.Protected()
- .Setup("Do", ItExpr.Is<int>(i => i % 2 == 0))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Protected()
- .Setup("GetUser", ItExpr.Is<int>(i => i < 0))
- .Throws(new ArgumentException());
-
-
- mock.Protected()
- .Setup("HasInventory",
- ItExpr.IsAny<string>(),
- ItExpr.IsInRange(0, 100, Range.Inclusive))
- .Returns(false);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+"))
- .Returns(1);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+", RegexOptions.IgnoreCase))
- .Returns(1);
-
-
- [Matcher]
- public Order IsBigOrder()
- {
- return Match<Order>.Create(
- o => o.GrandTotal >= 5000,
- /* a friendly expression to render on failures */
- () => IsBigOrder());
- }
-
- This method can be used in any mock setup invocation:
-
- mock.Setup(m => m.Submit(IsBigOrder()).Throws<UnauthorizedAccessException>();
-
- At runtime, Moq knows that the return value was a matcher (note that the method MUST be
- annotated with the [Matcher] attribute in order to determine this) and
- evaluates your predicate with the actual value passed into your predicate.
-
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return Match<IEnumerable<Order>>.Create(orders => orders.Contains(order));
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
-
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- mock.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.True(order.IsFilled);
-
- The following example shows how to use the
- // Arrange
- var order = new Order(TALISKER, 50);
- var mock = new Mock<IWarehouse>();
-
- // shows how to expect a value within a range
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
- // shows how to throw for unexpected calls.
- mock.Setup(x => x.Remove(
- It.IsAny<string>(),
- It.IsAny<int>()))
- .Throws(new InvalidOperationException());
-
- // Act
- order.Fill(mock.Object);
-
- // Assert
- Assert.False(order.IsFilled);
-
-
- // Typed instance, not the mock, is retrieved from some test API.
- HttpContextBase context = GetMockContext();
-
- // context.Request is the typed object from the "real" API
- // so in order to add a setup to it, we need to get
- // the mock that "owns" it
- Mock<HttpRequestBase> request = Mock.Get(context.Request);
- mock.Setup(req => req.AppRelativeCurrentExecutionFilePath)
- .Returns(tempUrl);
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Verifiable().Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory.
- this.Verify();
-
-
- var mock = new Mock<IWarehouse>();
- this.Setup(x => x.HasInventory(TALISKER, 50)).Returns(true);
- ...
- // other test code
- ...
- // Will throw if the test code has didn't call HasInventory, even
- // that expectation was not marked as verifiable.
- this.VerifyAll();
-
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
- // add IDisposable interface
- var disposable = mock.As<IDisposable>();
- disposable.Setup(d => d.Dispose()).Verifiable();
-
- var mock = new Mock<IFormatProvider>();
- var mock = new Mock<MyProvider>(someArgument, 25);
- var mock = new Mock<IFormatProvider>(MockBehavior.Relaxed);
- var mock = new Mock<MyProvider>(someArgument, 25);
-
- var mock = new Mock<IProcessor>();
- mock.Setup(x => x.Execute("ping"));
-
-
- mock.Setup(x => x.HasInventory("Talisker", 50)).Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- mock.SetupSet(x => x.Suspended = true);
-
-
- var mock = new Mock<IHaveValue>();
- mock.Stub(v => v.Value);
-
- After the
- IHaveValue v = mock.Object;
-
- v.Value = 5;
- Assert.Equal(5, v.Value);
-
-
- var mock = new Mock<IHaveValue>();
- mock.SetupProperty(v => v.Value, 5);
-
- After the
- IHaveValue v = mock.Object;
- // Initial value was stored
- Assert.Equal(5, v.Value);
-
- // New value set which changes the initial value
- v.Value = 6;
- Assert.Equal(6, v.Value);
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IProcessor>();
- // exercise mock
- //...
- // Will throw if the test code didn't call Execute with a "ping" string argument.
- mock.Verify(proc => proc.Execute("ping"));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50));
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't call HasInventory.
- mock.Verify(warehouse => warehouse.HasInventory(TALISKER, 50), "When filling orders, inventory has to be checked");
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't retrieve the IsClosed property.
- mock.VerifyGet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed = true, "Warehouse should always be closed after the action");
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.PropertyChanged -= null, new PropertyChangedEventArgs("Name"));
-
-
- var mockView = new Mock<IOrdersView>();
- var presenter = new OrdersPresenter(mockView.Object);
-
- // Check that the presenter has no selection by default
- Assert.Null(presenter.SelectedOrder);
-
- // Raise the event with a specific arguments data
- mockView.Raise(v => v.SelectionChanged += null, new OrderEventArgs { Order = new Order("moq", 500) });
-
- // Now the presenter reacted to the event, and we have a selected order
- Assert.NotNull(presenter.SelectedOrder);
- Assert.Equal("moq", presenter.SelectedOrder.ProductName);
-
-
- var mock = new Mock<IViewModel>();
-
- mock.Raise(x => x.MyEvent -= null, "Name", bool, 25);
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Setup(x => x.Remove(It.IsAny<string>())).Throws(new InvalidOperationException());
-
-
- mock.Setup(x => x.Do(It.Is<int>(i => i % 2 == 0)))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Setup(x => x.GetUser(It.Is<int>(i => i < 0)))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsInRange(0, 100, Range.Inclusive)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsIn(1, 2, 3)))
- .Returns(false);
-
-
- var values = new List<int> { 1, 2, 3 };
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(values)))
- .Returns(false);
-
-
- mock.Setup(x => x.HasInventory(
- It.IsAny<string>(),
- It.IsNotIn(1, 2, 3)))
- .Returns(false);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+"))).Returns(1);
-
-
- mock.Setup(x => x.Check(It.IsRegex("[a-z]+", RegexOptions.IgnoreCase))).Returns(1);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true);
-
-
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback((string command) => Console.WriteLine(command));
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMostOnce();
-
-
- var mock = new Mock<ICommand>();
- mock.Setup(foo => foo.Execute("ping"))
- .AtMost( 5 );
-
-
- var mock = new Mock<IContainer>();
-
- mock.Setup(add => add.Add(It.IsAny<string>(), It.IsAny<object>()))
- .Raises(add => add.Added += null, EventArgs.Empty);
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable();
-
-
- mock.Expect(x => x.Execute("ping"))
- .Returns(true)
- .Verifiable("Ping should be executed always!");
-
-
- mock.Setup(x => x.Execute(""))
- .Throws(new ArgumentException());
-
-
- mock.Setup(x => x.Execute(""))
- .Throws<ArgumentException>();
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2) => Console.WriteLine(arg1 + arg2));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3) => Console.WriteLine(arg1 + arg2 + arg3));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4) => Console.WriteLine(arg1 + arg2 + arg3 + arg4));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15));
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>(),
- It.IsAny<string>()))
- .Callback((arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15, arg16) => Console.WriteLine(arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16));
-
-
- var called = false;
- mock.Setup(x => x.Execute())
- .Callback(() => called = true)
- .Returns(true);
-
- Note that in the case of value-returning methods, after the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Callback(command => Console.WriteLine(command))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2) => arg1 + arg2);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3) => arg1 + arg2 + arg3);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4) => arg1 + arg2 + arg3 + arg4);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5) => arg1 + arg2 + arg3 + arg4 + arg5);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15);
-
-
- mock.Setup(x => x.Execute(
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>(),
- It.IsAny<int>()))
- .Returns((string arg1, string arg2, string arg3, string arg4, string arg5, string arg6, string arg7, string arg8, string arg9, string arg10, string arg11, string arg12, string arg13, string arg14, string arg15, string arg16) => arg1 + arg2 + arg3 + arg4 + arg5 + arg6 + arg7 + arg8 + arg9 + arg10 + arg11 + arg12 + arg13 + arg14 + arg15 + arg16);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(true);
-
-
- mock.Setup(x => x.Execute("ping"))
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the method
- is executed and the value the
- mock.Setup(x => x.Execute(It.IsAny<string>()))
- .Returns((string command) => returnValues[command]);
-
-
- mock.SetupGet(x => x.Suspended)
- .Callback(() => called = true)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(true);
-
-
- mock.SetupGet(x => x.Suspended)
- .Returns(() => returnValues[0]);
-
- The lambda expression to retrieve the return value is lazy-executed,
- meaning that its value may change depending on the moment the property
- is retrieved and the value the
- mock.SetupSet(x => x.Suspended)
- .Callback((bool state) => Console.WriteLine(state));
-
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- repository.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the repository
- to create loose mocks and later verify only verifiable setups:
-
- var repository = new MockRepository(MockBehavior.Loose);
-
- var foo = repository.Create<IFoo>();
- var bar = repository.Create<IBar>();
-
- // this setup will be verified when we verify the repository
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the repository
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- repository.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the repository with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var repository = new MockRepository(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = repository.Create<IFoo>(MockBehavior.Loose);
- var bar = repository.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- repository.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // no need to call Verifiable() on the setup
- // as we'll be validating all of them anyway.
- foo.Setup(f => f.Do());
- bar.Setup(b => b.Redo());
-
- // exercise the mocks here
-
- factory.VerifyAll();
- // At this point all setups are already checked
- // and an optional MockException might be thrown.
- // Note also that because the mocks are strict, any invocation
- // that doesn't have a matching setup will also throw a MockException.
-
- The following examples shows how to setup the factory
- to create loose mocks and later verify only verifiable setups:
-
- var factory = new MockFactory(MockBehavior.Loose);
-
- var foo = factory.Create<IFoo>();
- var bar = factory.Create<IBar>();
-
- // this setup will be verified when we verify the factory
- foo.Setup(f => f.Do()).Verifiable();
-
- // this setup will NOT be verified
- foo.Setup(f => f.Calculate());
-
- // this setup will be verified when we verify the factory
- bar.Setup(b => b.Redo()).Verifiable();
-
- // exercise the mocks here
- // note that because the mocks are Loose, members
- // called in the interfaces for which no matching
- // setups exist will NOT throw exceptions,
- // and will rather return default values.
-
- factory.Verify();
- // At this point verifiable setups are already checked
- // and an optional MockException might be thrown.
-
- The following examples shows how to setup the factory with a
- default strict behavior, overriding that default for a
- specific mock:
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- // this particular one we want loose
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
- var bar = factory.Create<IBar>();
-
- // specify setups
-
- // exercise the mocks here
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>();
- // use mock on tests
-
- factory.VerifyAll();
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>("Foo", 25, true);
- // use mock on tests
-
- factory.Verify();
-
-
- var factory = new MockFactory(MockBehavior.Strict);
-
- var foo = factory.Create<IFoo>(MockBehavior.Loose);
-
-
- var factory = new MockFactory(MockBehavior.Default);
-
- var mock = factory.Create<MyBase>(MockBehavior.Strict, "Foo", 25, true);
-
-
- [Matcher]
- public Order IsBigOrder()
- {
- return Match<Order>.Create(
- o => o.GrandTotal >= 5000,
- /* a friendly expression to render on failures */
- () => IsBigOrder());
- }
-
- This method can be used in any mock setup invocation:
-
- mock.Setup(m => m.Submit(IsBigOrder()).Throws<UnauthorizedAccessException>();
-
- At runtime, Moq knows that the return value was a matcher (note that the method MUST be
- annotated with the [Matcher] attribute in order to determine this) and
- evaluates your predicate with the actual value passed into your predicate.
-
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return Match<IEnumerable<Order>>.Create(orders => orders.Contains(order));
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
-
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
- }
-
- Now we can invoke this static method instead of an argument in an
- invocation:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- Note that the return value from the compiler matcher is irrelevant.
- This method will never be called, and is just used to satisfy the
- compiler and to signal Moq that this is not a method that we want
- to be invoked at runtime.
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
-
- At runtime, the mocked method will be invoked with a specific
- list of orders. This value will be passed to this runtime
- matcher as the first argument, while the second argument is the
- one specified in the setup (
- public static class Orders
- {
- [Matcher]
- public static IEnumerable<Order> Contains(Order order)
- {
- return null;
- }
-
- public static bool Contains(IEnumerable<Order> orders, Order order)
- {
- return orders.Contains(order);
- }
- }
-
- And the concrete test using this matcher:
-
- var order = new Order { ... };
- var mock = new Mock<IRepository<Order>>();
-
- mock.Setup(x => x.Save(Orders.Contains(order)))
- .Throws<ArgumentException>();
-
- // use mock, invoke Save, and have the matcher filter.
-
-
- mock.SetupSet(x => x.Suspended);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- var mock = new Mock<IWarehouse>();
- // exercise mock
- //...
- // Will throw if the test code didn't set the IsClosed property.
- mock.VerifySet(warehouse => warehouse.IsClosed);
-
-
- // Throws an exception for a call to Remove with a null string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsNull<string>())
- .Throws(new InvalidOperationException());
-
-
- // Throws an exception for a call to Remove with any string value.
- mock.Protected()
- .Setup("Remove", ItExpr.IsAny<string>())
- .Throws(new InvalidOperationException());
-
-
- mock.Protected()
- .Setup("Do", ItExpr.Is<int>(i => i % 2 == 0))
- .Returns(1);
-
- This example shows how to throw an exception if the argument to the
- method is a negative number:
-
- mock.Protected()
- .Setup("GetUser", ItExpr.Is<int>(i => i < 0))
- .Throws(new ArgumentException());
-
-
- mock.Protected()
- .Setup("HasInventory",
- ItExpr.IsAny<string>(),
- ItExpr.IsInRange(0, 100, Range.Inclusive))
- .Returns(false);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+"))
- .Returns(1);
-
-
- mock.Protected()
- .Setup("Check", ItExpr.IsRegex("[a-z]+", RegexOptions.IgnoreCase))
- .Returns(1);
-
- s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
Creates a buffer.
-Number of bytes in the blob.
The address of a reference to the ID3DBlob interface that is used to retrieve the buffer.
Returns one of the following Direct3D 10 Return Codes.
The latest D3dcompiler_nn.dll contains the
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-A multithread interface accesses multithread settings and can only be used if the thread-safe layer is turned on.
-This interface is obtained by querying it from the
Enter a device's critical section.
-Entering a device's critical section prevents other threads from simultaneously calling that device's methods (if multithread protection is set to true), calling DXGI methods, and calling the methods of all resource, view, shader, state, and asynchronous interfaces.
This function should be used in multithreaded applications when there is a series of graphics commands that must happen in order. This function is typically called at the beginning of the series of graphics commands, and
Leave a device's critical section.
-This function is typically used in multithreaded applications when there is a series of graphics commands that must happen in order.
Turn multithreading on or off.
-True to turn multithreading on, false to turn it off.
True if multithreading was turned on prior to calling this method, false otherwise.
Find out if multithreading is turned on or not.
-Whether or not multithreading is turned on. True means on, false means off.
Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
Creates a buffer.
-Number of bytes in the blob.
The address of a reference to the ID3DBlob interface that is used to retrieve the buffer.
Returns one of the following Direct3D 10 Return Codes.
The latest D3dcompiler_nn.dll contains the
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-A multithread interface accesses multithread settings and can only be used if the thread-safe layer is turned on.
-This interface is obtained by querying it from the
Enter a device's critical section.
-Entering a device's critical section prevents other threads from simultaneously calling that device's methods (if multithread protection is set to true), calling DXGI methods, and calling the methods of all resource, view, shader, state, and asynchronous interfaces.
This function should be used in multithreaded applications when there is a series of graphics commands that must happen in order. This function is typically called at the beginning of the series of graphics commands, and
Leave a device's critical section.
-This function is typically used in multithreaded applications when there is a series of graphics commands that must happen in order.
Turn multithreading on or off.
-True to turn multithreading on, false to turn it off.
True if multithreading was turned on prior to calling this method, false otherwise.
Find out if multithreading is turned on or not.
-Whether or not multithreading is turned on. True means on, false means off.
Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Targets features supported by Direct3D 11.1 including Direct3D device sharing. Device sharing enables Direct3D 10 and Direct3D 11 APIs to use one underlying rendering device. For more information about device sharing, see
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-A multithread interface accesses multithread settings and can only be used if the thread-safe layer is turned on.
-This interface is obtained by querying it from the ID3D10Device Interface using IUnknown::QueryInterface.
-Enter a device's critical section.
-Entering a device's critical section prevents other threads from simultaneously calling that device's methods (if multithread protection is set to true), calling DXGI methods, and calling the methods of all resource, view, shader, state, and asynchronous interfaces.
This function should be used in multithreaded applications when there is a series of graphics commands that must happen in order. This function is typically called at the beginning of the series of graphics commands, and
Leave a device's critical section.
-This function is typically used in multithreaded applications when there is a series of graphics commands that must happen in order.
Turn multithreading on or off.
-True to turn multithreading on, false to turn it off.
True if multithreading was turned on prior to calling this method, false otherwise.
Find out if multithreading is turned on or not.
-Whether or not multithreading is turned on. True means on, false means off.
Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
The IAudioClient::Initialize and IAudioClient::IsFormatSupported methods use the constants defined in the
In shared mode, the client can share the audio endpoint device with clients that run in other user-mode processes. The audio engine always supports formats for client streams that match the engine's mix format. In addition, the audio engine might support another format if the Windows audio service can insert system effects into the client stream to convert the client format to the mix format.
In exclusive mode, the Windows audio service attempts to establish a connection in which the client has exclusive access to the audio endpoint device. In this mode, the audio engine inserts no system effects into the local stream to aid in the creation of the connection point. Either the audio device can handle the specified format directly or the method fails.
For more information about shared-mode and exclusive-mode streams, see User-Mode Audio Components.
-The audio stream will run in shared mode. For more information, see Remarks.
The audio stream will run in exclusive mode. For more information, see Remarks.
The AudioSessionState enumeration defines constants that indicate the current state of an audio session.
-When a client opens a session by assigning the first stream to the session (by calling the IAudioClient::Initialize method), the initial session state is inactive. The session state changes from inactive to active when a stream in the session begins running (because the client has called the IAudioClient::Start method). The session changes from active to inactive when the client stops the last running stream in the session (by calling the IAudioClient::Stop method). The session state changes to expired when the client destroys the last stream in the session by releasing all references to the stream object.
The system volume-control program, Sndvol, displays volume controls for both active and inactive sessions. Sndvol stops displaying the volume control for a session when the session state changes to expired. For more information about Sndvol, see Audio Sessions.
The IAudioSessionControl::GetState and IAudioSessionEvents::OnStateChanged methods use the constants defined in the AudioSessionState enumeration.
For more information about session states, see Audio Sessions.
-The audio session is inactive. (It contains at least one stream, but none of the streams in the session is currently running.)
The audio session is active. (At least one of the streams in the session is running.)
The audio session has expired. (It contains no streams.)
[This documentation is preliminary and is subject to change.]
Specifies the category of an audio stream.
-Media, such as music or streaming audio.
Real-time communications, such as VOIP or chat.
Voice narration, such as a screen reader or ebook reader.
Alert sounds.
Sound effects.
Game sound effects.
Background audio for games.
Other audio stream.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing The
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
An
Sets application-defined data to the object and associates that data with a
A
The size of the object's data.
A reference to the object's data.
Returns one of the DXGI_ERROR values.
SetPrivateData makes a copy of the specified data and stores it with the object.
Private data that SetPrivateData stores in the object occupies the same storage space as private data that is stored by associated Direct3D objects (for example, by a Microsoft Direct3D?11 device through
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is "<unnamed>". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the well-known private data
static const char c_szName[] = "My name";
- hr = pContext->SetPrivateData( You can use
Set an interface in the object's private data.
-A
The interface to set.
Returns one of the following DXGI_ERROR.
This API associates an interface reference with the object.
When the interface is set its reference count is incremented. When the data are overwritten (by calling SPD or SPDI with the same
Get a reference to the object's data.
-A
The size of the data.
Pointer to the data.
Returns one of the following DXGI_ERROR.
If the data returned is a reference to an
Gets the parent of the object.
-The ID of the requested interface.
The address of a reference to the parent object.
Returns one of the DXGI_ERROR values.
Enumerate adapter (video card) outputs.
-The index of the output.
The address of a reference to an
A code that indicates success or failure (see DXGI_ERROR). Will return
When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the reference to the output interface, EnumOutputs increments the output interface's reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.
EnumOutputs first returns the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumOutputs then returns other outputs.
-Gets a DXGI 1.0 description of an adapter (or video card).
-A reference to a
Returns
Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create null ;
- } Checks whether the system supports a device interface for a graphics component.
-The
The user mode driver version of InterfaceName. This is returned only if the interface is supported. This parameter can be
Note??You can use CheckInterfaceSupport only to check whether a Direct3D 10.x interface is supported, and only on Windows Vista SP1 and later versions of the operating system. If you try to use CheckInterfaceSupport to check whether a Direct3D 11.x and later version interface is supported, CheckInterfaceSupport returns
Gets a DXGI 1.0 description of an adapter (or video card).
-Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create null ;
- } An
The
The object returned by the Direct3D create device functions implements the
Returns the adapter for the specified device.
-The address of an
Returns
If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Returns a surface. This method is used internally and you should not call it directly in your application.
-A reference to a
The number of surfaces to create.
A DXGI_USAGE flag that specifies how the surface is expected to be used.
An optional reference to a
The address of an
Returns
The CreateSurface method creates a buffer to exchange data between one or more devices. It is used internally, and you should not directly call it.
The runtime automatically creates an
Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Sets the GPU thread priority.
-A value that specifies the required GPU thread priority. This value must be between -7 and 7, inclusive, where 0 represents normal priority.
Return
The values for the Priority parameter function as follows:
To use the SetGPUThreadPriority method, you should have a comprehensive understanding of GPU scheduling. You should profile your application to ensure that it behaves as intended. If used inappropriately, the SetGPUThreadPriority method can impede rendering speed and result in a poor user experience.
-Gets the GPU thread priority.
-A reference to a variable that receives a value that indicates the current GPU thread priority. The value will be between -7 and 7, inclusive, where 0 represents normal priority.
Return
Returns the adapter for the specified device.
-If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Gets or sets the GPU thread priority.
-Inherited from objects that are tied to the device so that they can retrieve a reference to it.
-Retrieves the device.
-The reference id for the device.
The address of a reference to the device.
A code that indicates success or failure (see DXGI_ERROR).
The type of interface that is returned can be any interface published by the device. For example, it could be an
An
Create a factory by calling CreateDXGIFactory.
Because a Direct3D device can be created without creating a swap chain, you might need to retrieve the factory that is used to create the device in order to create a swap chain.
- This can be accomplished by requesting the
See
Enumerates the adapters (video cards).
-The index of the adapter to enumerate.
The address of a reference to an
Returns
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters then returns other adapters with outputs.
-Allows DXGI to monitor an application's message queue for the alt-enter key sequence (which causes the application to switch from windowed to full screen or vice versa).
-The handle of the window that is to be monitored. This parameter can be
One or more of the following values:
The combination of WindowHandle and Flags informs DXGI to stop monitoring window messages for the previously-associated window.
If the application switches to full-screen mode, DXGI will choose a full-screen resolution to be the smallest supported resolution that is larger or the same size as the current back buffer size.
Applications can make some changes to make the transition from windowed to full screen more efficient. For example, on a WM_SIZE message, the application should release any outstanding swap-chain back buffers, call
While windowed, the application can, if it chooses, restrict the size of its window's client area to sizes to which it is comfortable rendering. A fully flexible application would make no such restriction, but UI elements or other design considerations can, of course, make this flexibility untenable. If the application further chooses to restrict its window's client area to just those that match supported full-screen resolutions, the application can field WM_SIZING, then check against
Applications that want to handle mode changes or Alt+Enter themselves should call MakeWindowAssociation with the
If a Metro style app calls MakeWindowAssociation, it fails with
A Microsoft Win32 application can use MakeWindowAssociation to control full-screen transitions through the Alt+Enter key combination and print screen behavior for full screen. For Metro style apps, because DXGI cannot perform full-screen transitions, Metro style app have no way to control full-screen transitions.
-Get the window through which the user controls the transition to and from full screen.
-A reference to a window handle.
If a Metro style app calls GetWindowAssociation, it fails with
[Starting with Direct3D 11.1, we recommend not to use CreateSwapChain anymore to create a swap chain. Instead, use CreateSwapChainForHwnd, CreateSwapChainForImmersiveWindow, or CreateSwapChainForCompositionSurface depending on how you want to create the swap chain.]
Creates a swap chain.
-
If you attempt to create a swap chain in full-screen mode, and full-screen mode is unavailable, the swap chain will be created in windowed mode and
If the buffer width or the buffer height is zero, the sizes will be inferred from the output window size in the swap-chain description.
Because the target output cannot be chosen explicitly when the swap-chain is created, you should not create a full-screen swap chain. This can reduce presentation performance if the swap chain size and the output window size do not match. Here are two ways to ensure that the sizes match:
If the swap chain is in full-screen mode, before you release it you must use SetFullscreenState to switch it to windowed mode. For more information about releasing a swap chain, see the "Destroying a Swap Chain" section of DXGI Overview.
You can specify
However, to use stereo presentation and to change resize behavior for the flip model, applications must use the IDXGIFactory2::CreateSwapChainForHwnd method. Otherwise, the back-buffer contents implicitly scale to fit the presentation target size; that is, you can't turn off scaling.
Notes for Metro style appsIf a Metro style app calls CreateSwapChain with full screen specified, CreateSwapChain fails.
Metro style apps call the IDXGIFactory2::CreateSwapChainForImmersiveWindow method to create a swap chain.
-Create an adapter interface that represents a software adapter.
-Handle to the software adapter's dll. HMODULE can be obtained with GetModuleHandle or LoadLibrary.
Address of a reference to an adapter (see
A software adapter is a DLL that implements the entirety of a device driver interface, plus emulation, if necessary, of kernel-mode graphics components for Windows. Details on implementing a software adapter can be found in the Windows Vista Driver Development Kit. This is a very complex development task, and is not recommended for general readers.
Calling this method will increment the module's reference count by one. The reference count can be decremented by calling FreeLibrary.
The typical calling scenario is to call LoadLibrary, pass the handle to CreateSoftwareAdapter, then immediately call FreeLibrary on the DLL and forget the DLL's HMODULE. Since the software adapter calls FreeLibrary when it is destroyed, the lifetime of the DLL will now be owned by the adapter, and the application is free of any further consideration of its lifetime.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
To create a factory, call the CreateDXGIFactory1 function.
-Enumerates both adapters (video cards) with or without outputs.
-The index of the adapter to enumerate.
The address of a reference to an
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters1 method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters1 increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters1 first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters1 next returns other adapters with outputs. EnumAdapters1 finally returns adapters without outputs.
-Informs an application of the possible need to re-enumerate adapters.
-IsCurrent returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Informs an application of the possible need to re-enumerate adapters.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Identifies the type of DXGI adapter.
-The
Specifies no flags.
Value always set to 0. This flag is reserved.
Flags that indicate how the back buffers should be rotated to fit the physical rotation of a monitor.
-Unspecified rotation.
Specifies no rotation.
Specifies 90 degrees of rotation.
Specifies 180 degrees of rotation.
Specifies 270 degrees of rotation.
Flags indicating how an image is stretched to fit a given monitor's resolution.
-Unspecified scaling.
Specifies no scaling. The image is centered on the display. This flag is typically used for a fixed-dot-pitch display (such as an LED display).
Specifies stretched scaling.
Flags indicating the method the raster uses to create an image on a surface.
-Scanline order is unspecified.
The image is created from the first scanline to the last without skipping any.
The image is created beginning with the upper field.
The image is created beginning with the lower field.
Status codes that can be returned by DXGI functions.
-Resource data formats which includes fully-typed and typeless formats. There is a list of format modifiers at the bottom of the page, that more fully describes each format type.
-A few formats have additional restrictions.
The following topics provide lists of the formats that particular hardware feature levels support:
For a list of the DirectXMath types that map to
Each enumeration value contains a format modifier which describes the data type.
| Format Modifiers | Description |
|---|---|
| _FLOAT | A floating-point value; 32-bit floating-point formats use IEEE 754 single-precision (s23e8 format): sign bit, 8-bit biased (127) exponent, and 23-bit mantissa. 16-bit floating-point formats use half-precision (s10e5 format): sign bit, 5-bit biased (15) exponent, and 10-bit mantissa. |
| _SINT | Two's complement signed integer. For example, a 3-bit SINT represents the values -4, -3, -2, -1, 0, 1, 2, 3. |
| _SNORM | Signed normalized integer; which is interpreted in a resource as a signed integer, and is interpreted in a shader as a signed normalized floating-point value in the range [-1, 1]. For an 2's complement number, the maximum value is 1.0f (a 5-bit value 01111 maps to 1.0f), and the minimum value is -1.0f (a 5-bit value 10000 maps to -1.0f). In addition, the second-minimum number maps to -1.0f (a 5-bit value 10001 maps to -1.0f). The resulting integer representations are evenly spaced floating-point values in the range (-1.0f...0.0f), and also a complementary set of representations for numbers in the range (0.0f...1.0f). |
| _SRGB | Standard RGB data, which roughly displays colors in a linear ramp of luminosity levels such that an average observer, under average viewing conditions, can view them on an average display. All 0's maps to 0.0f, and all 1's maps to 1.0f. The sequence of unsigned integer encodings between all 0's and all 1's represent a nonlinear progression in the floating-point interpretation of the numbers between 0.0f to 1.0f. For more detail, see the SRGB color standard, IEC 61996-2-1, at IEC (International Electrotechnical Commission). Conversion to or from sRGB space is automatically done by D3DX10 or D3DX9 texture-load functions. If the format has an alpha channel, the alpha data is also stored in sRGB color space. |
| _TYPELESS | Typeless data, with a defined number of bits. Typeless formats are designed for creating typeless resources; that is, a resource whose size is known, but whose data type is not yet fully defined. When a typeless resource is bound to a shader, the application or shader must resolve the format type (which must match the number of bits per component in the typeless format). A typeless format contains one or more subformats; each subformat resolves the data type. For example, in the R32G32B32 group, which defines types for three-component 96-bit data, there is one typeless format and three fully typed subformats. |
| _UINT | Unsigned integer. For instance, a 3-bit UINT represents the values 0, 1, 2, 3, 4, 5, 6, 7. |
| _UNORM | Unsigned normalized integer; which is interpreted in a resource as an unsigned integer, and is interpreted in a shader as an unsigned normalized floating-point value in the range [0, 1]. All 0's maps to 0.0f, and all 1's maps to 1.0f. A sequence of evenly spaced floating-point values from 0.0f to 1.0f are represented. For instance, a 2-bit UNORM represents 0.0f, 1/3, 2/3, and 1.0f. |
?
New Resource FormatsDirect3D 10 offers new data compression formats for compressing high-dynamic range (HDR) lighting data, normal maps and heightfields to a fraction of their original size. These compression types include:
The block compression formats can be used for any of the 2D or 3D texture types ( Texture2D, Texture2DArray, Texture3D, or TextureCube) including mipmap surfaces. The block compression techniques require texture dimensions to be a multiple of 4 (since the implementation compresses on blocks of 4x4 texels). In the texture sampler, compressed formats are always decompressed before texture filtering.
-The format is not known.
A four-component, 128-bit typeless format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit floating-point format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit unsigned-integer format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit signed-integer format that supports 32 bits per channel including alpha. 1
A three-component, 96-bit typeless format that supports 32 bits per color channel.
A three-component, 96-bit floating-point format that supports 32 bits per color channel.
A three-component, 96-bit unsigned-integer format that supports 32 bits per color channel.
A three-component, 96-bit signed-integer format that supports 32 bits per color channel.
A four-component, 64-bit typeless format that supports 16 bits per channel including alpha.
A four-component, 64-bit floating-point format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-integer format that supports 16 bits per channel including alpha.
A two-component, 64-bit typeless format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit floating-point format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit unsigned-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit signed-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit typeless format that supports 32 bits for the red channel, 8 bits for the green channel, and 24 bits are unused.
A 32-bit floating-point component, and two unsigned-integer components (with an additional 32 bits). This format supports 32-bit depth, 8-bit stencil, and 24 bits are unused.
A 32-bit floating-point component, and two typeless components (with an additional 32 bits). This format supports 32-bit red channel, 8 bits are unused, and 24 bits are unused.
A 32-bit typeless component, and two unsigned-integer components (with an additional 32 bits). This format has 32 bits unused, 8 bits for green channel, and 24 bits are unused.
A four-component, 32-bit typeless format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-integer format that supports 10 bits for each color and 2 bits for alpha.
Three partial-precision floating-point numbers encoded into a single 32-bit value (a variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There are no sign bits, and there is a 5-bit biased (15) exponent for each channel, 6-bit mantissa for R and G, and a 5-bit mantissa for B, as shown in the following illustration.
A four-component, 32-bit typeless format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized integer sRGB format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-integer format that supports 8 bits per channel including alpha.
A two-component, 32-bit typeless format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit floating-point format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit unsigned-normalized-integer format that supports 16 bits each for the green and red channels.
A two-component, 32-bit unsigned-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-normalized-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A single-component, 32-bit typeless format that supports 32 bits for the red channel.
A single-component, 32-bit floating-point format that supports 32 bits for depth.
A single-component, 32-bit floating-point format that supports 32 bits for the red channel.
A single-component, 32-bit unsigned-integer format that supports 32 bits for the red channel.
A single-component, 32-bit signed-integer format that supports 32 bits for the red channel.
A two-component, 32-bit typeless format that supports 24 bits for the red channel and 8 bits for the green channel.
A 32-bit z-buffer format that supports 24 bits for depth and 8 bits for stencil.
A 32-bit format, that contains a 24 bit, single-component, unsigned-normalized integer, with an additional typeless 8 bits. This format has 24 bits red channel and 8 bits unused.
A 32-bit format, that contains a 24 bit, single-component, typeless format, with an additional 8 bit unsigned integer component. This format has 24 bits unused and 8 bits green channel.
A two-component, 16-bit typeless format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A single-component, 16-bit typeless format that supports 16 bits for the red channel.
A single-component, 16-bit floating-point format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for depth.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-integer format that supports 16 bits for the red channel.
A single-component, 8-bit typeless format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format for alpha only.
A single-component, 1-bit unsigned-normalized integer format that supports 1 bit for the red channel. 2.
Three partial-precision floating-point numbers encoded into a single 32-bit value all sharing the same 5-bit exponent (variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There is no sign bit, and there is a shared 5-bit biased (15) exponent and a 9-bit mantissa for each channel, as shown in the following illustration. 2.
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the UYVY format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the YUY2 format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A three-component, 16-bit unsigned-normalized-integer format that supports 5 bits for blue, 6 bits for green, and 5 bits for red.
A four-component, 16-bit unsigned-normalized-integer format that supports 5 bits for each color channel and 1-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8 bits unused.
A four-component, 32-bit 2.8-biased fixed-point format that supports 10 bits for each color channel and 2-bit alpha.
A four-component, 32-bit typeless format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit typeless format that supports 8 bits for each color channel, and 8 bits are unused. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each color channel, and 8 bits are unused. 4
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Flags indicating the memory location of a resource.
-The resource is located in video memory.
At least some of the resource is located in CPU memory.
At least some of the resource has been paged out to the hard drive.
Options for swap-chain behavior.
-This enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
Swap chains that you create in full-screen mode with the
Swap chains that you create with the IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForImmersiveWindow, and IDXGIFactory2::CreateSwapChainForCompositionSurface methods are not protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is not set and are protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is set. When swap chains are protected, screen scraping is prevented and, in full-screen mode, presented content is not accessible through the desktop duplication APIs.
-Set this flag to turn off automatic image rotation; that is, do not perform a rotation when transferring the contents of the front buffer to the monitor. Use this flag to avoid a bandwidth penalty when an application expects to handle rotation. This option is valid only during full-screen mode.
Set this flag to enable an application to switch modes by calling
Set this flag to enable an application to render using GDI on a swap chain or a surface. This will allow the application to call
Options for handling pixels in a display surface after calling
This enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
The primary difference between presentation models is how back-buffer contents get to the Desktop Window Manager (DWM) for composition. In the bitblt model, which is used with the
Regardless of whether the flip model is more efficient, an application still might choose the bitblt model for the following reasons:
The bitblt model is the only way to mix GDI and DirectX presentation.
In the flip model, the application must create the swap chain with
Creates a DXGI 1.1 factory that generates objects used to enumerate and specify video graphics settings.
-The globally unique identifier (
Address of a reference to an
Returns
Use a DXGI 1.1 factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the full-screen display mode.
If the CreateDXGIFactory1 function succeeds, the reference count on the
This entry point is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Note??Do not mix the use of DXGI 1.0 (
Creates a DXGI 1.0 factory that generates objects used to enumerate and specify video graphics settings.
-The globally unique identifier (
Address of a reference to an
Returns
Use a DXGI factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the fullscreen display mode.
If the CreateDXGIFactory function succeeds, the reference count on the
Note??Do not mix the use of DXGI 1.0 (
The CreateDXGIFactory function does not exist for Metro style apps. Instead, Metro style apps use the CreateDXGIFactory1 function.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
Gets a DXGI 1.1 description of an adapter (or video card).
-A reference to a
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
Gets a DXGI 1.1 description of an adapter (or video card).
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
An
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
The
Sets the number of frames that the system is allowed to queue for rendering.
-The maximum number of back buffer frames that a driver can queue. The value defaults to 3, but can range from 1 to 16. A value of 0 will reset latency to the default. For multi-head devices, this value is specified per-head.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets the number of frames that the system is allowed to queue for rendering.
-This value is set to the number of frames that can be queued for render. This value defaults to 3, but can range from 1 to 16.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets or sets the number of frames that the system is allowed to queue for rendering.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Using a key, acquires exclusive rendering access to a shared resource.
-The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, acquires exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method will succeed when the device that currently owns the surface calls the
The time-out interval, in milliseconds. This method will return if the interval elapses, and the keyed mutex has not been released using the specified Key. If this value is set to zero, the AcquireSync method will test to see if the keyed mutex has been released and returns immediately. If this value is set to INFINITE, the time-out interval will never elapse.
Return
If the owning device attempted to create another keyed mutex on the same shared resource, AcquireSync returns E_FAIL.
AcquireSync can also return the following DWORD constants. Therefore, you should explicitly check for these constants. If you only use the SUCCEEDED macro on the return value to determine if AcquireSync succeeded, you will not catch these constants.
The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, releases exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method succeeds when the device that currently owns the surface calls the ReleaseSync method using the same value. This value can be any UINT64 value.
Returns
If the device attempted to release a keyed mutex that is not valid or owned by the device, ReleaseSync returns E_FAIL.
The ReleaseSync method releases a lock to a surface that is shared between multiple devices. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
After you call the ReleaseSync method, the shared resource is unset from the rendering pipeline.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
An
To see the outputs available, use
Get a description of the output.
-A reference to the output description (see
Returns a code that indicates success or failure.
[Starting with Direct3D 11.1, we recommend not to use GetDisplayModeList anymore to retrieve the matching display mode. Instead, use IDXGIOutput1::GetDisplayModeList1, which supports stereo display mode.]
Gets the display modes that match the requested format and other input options.
-Returns one of the following DXGI_ERROR. It is rare, but possible, that the display modes available can change immediately after calling this method, in which case
In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.
UINT num = 0;
- [Starting with Direct3D 11.1, we recommend not to use FindClosestMatchingMode anymore to find the display mode that most closely matches the requested display mode. Instead, use IDXGIOutput1::FindClosestMatchingMode1, which supports stereo display mode.]
Finds the display mode that most closely matches the requested display mode.
-Returns one of the following DXGI_ERROR.
FindClosestMatchingMode behaves similarly to the IDXGIOutput1::FindClosestMatchingMode1 except FindClosestMatchingMode considers only the mono display modes. IDXGIOutput1::FindClosestMatchingMode1 considers only stereo modes if you set the Stereo member in the DXGI_MODE_DESC1 structure that pModeToMatch points to, and considers only mono modes if Stereo is not set.
IDXGIOutput1::FindClosestMatchingMode1 returns a matched display-mode set with only stereo modes or only mono modes. - FindClosestMatchingMode behaves as though you specified the input mode as mono.
-Halt a thread until the next vertical blank occurs.
-Returns one of the following DXGI_ERROR.
A vertical blank occurs when the raster moves from the lower right corner to the upper left corner to begin drawing the next frame.
-Takes ownership of an output.
-A reference to the
Set to TRUE to enable other threads or applications to take ownership of the device; otherwise, set to
Returns one of the DXGI_ERROR values.
When you are finished with the output, call
TakeOwnership should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.
Notes for Metro style appsIf a Metro style app uses TakeOwnership, it fails with
Releases ownership of the output.
-If you are not using a swap chain, get access to an output by calling
Gets a description of the gamma-control capabilities.
-A reference to a description of the gamma-control capabilities (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Sets the gamma controls.
-A reference to an array of gamma controls (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Gets the gamma control settings.
-An array of gamma control settings (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Changes the display mode.
-A reference to a surface (see
Returns one of the DXGI_ERROR values.
This method should only be called between
If a Metro style app uses SetDisplaySurface, it fails with
[Starting with Direct3D 11.1, we recommend not to use GetDisplaySurfaceData anymore to retrieve the current display surface. Instead, use IDXGIOutput1::GetDisplaySurfaceData1, which supports stereo display mode.]
Gets a copy of the current display surface.
-Returns one of the DXGI_ERROR values.
Use
Gets statistics about recently rendered frames.
-A reference to frame statistics (see
If this function succeeds, it returns
This API is similar to
Note??Calling this method is only supported while in full-screen mode.
- UINT num = 0;
- DXGI_FORMAT format = DXGI_FORMAT_R32G32B32A32_FLOAT;
- UINT flags = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ... DXGI_MODE_DESC * pDescs = new DXGI_MODE_DESC[num];
- pOutput->GetDisplayModeList( format, flags, &num, pDescs);
-
-
- Get a description of the output.
-Gets a description of the gamma-control capabilities.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets or sets the gamma control settings.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets statistics about recently rendered frames.
-This API is similar to
Note??Calling this method is only supported while in full-screen mode.
-An
To find out what type of memory a resource is currently located in, use
You can retrieve the
[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
-Returns one of the DXGI_ERROR values.
You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-A reference to a usage flag (see DXGI_USAGE). For Direct3D 10, a surface can be used as a shader input or a render-target output.
Returns one of the following DXGI_ERROR.
Set the priority for evicting the resource from memory.
-The priority is one of the following values:
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI for determining how to populate overcommitted memory.
You can set priority levels other than the defined values when appropriate. For example, you can set a resource with a priority level of 0x78000001 to indicate that the resource is slightly above normal.
-Get the eviction priority.
-A reference to the eviction priority, which determines when a resource can be evicted from memory.
The following defined values are possible.
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
-You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-Get or sets the eviction priority.
-The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-The
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
The runtime automatically creates an
Get a description of the surface.
-A reference to the surface description (see
Returns
Get a reference to the data contained in the surface, and deny GPU access to the surface.
-A reference to the surface data (see
CPU read-write flags. These flags can be combined with a logical OR.
Returns
Use
Invalidate the reference to the surface retrieved by
Returns
Get a description of the surface.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
Any object that supports
The runtime automatically creates an
Returns a device context (DC) that allows you to render to a Microsoft DirectX Graphics Infrastructure (DXGI) surface using Windows Graphics Device Interface (GDI).
-A Boolean value that specifies whether to preserve Direct3D contents in the GDI DC. TRUE directs the runtime not to preserve Direct3D contents in the GDI DC; that is, the runtime discards the Direct3D contents.
A reference to an
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
After you use the GetDC method to retrieve a DC, you can render to the DXGI surface by using GDI. The GetDC method readies the surface for GDI rendering and allows inter-operation between DXGI and GDI technologies.
Keep the following in mind when using this method:
You can also call GetDC on the back buffer at index 0 of a swap chain by obtaining an
null ;
- null ;
- ...
- //Setup the device and and swapchain
- g_pSwapChain->GetBuffer(0, __uuidof(null ); Releases the GDI device context (DC) that is associated with the current surface and allows you to use Direct3D to render.
-A reference to a
You can pass a reference to an empty
If this method succeeds, it returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the ReleaseDC method to release the DC and indicate that your application finished all GDI rendering to this surface. You must call the ReleaseDC method before you can use Direct3D to perform additional rendering.
Prior to resizing buffers you must release all outstanding DCs.
-An
You can create a swap chain in several ways. If your application uses Direct3D, create a swap chain when you create a device by
- calling
[Starting with Direct3D 11.1, we recommend not to use Present anymore to present a rendered image. Instead, use IDXGISwapChain1::Present1.]
Presents a rendered image to the user.
-Possible return values include:
Note??The Present method can return either
For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.
Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.
| Differences between Direct3D 9 and Direct3D 10: Specifying |
?
For flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set, a successful presentation unbinds back buffer 0 from the graphics pipeline, except for when you pass the
Suppose the following frames with sync-interval values are queued from oldest (A) to newest (E) before you call Present.
A: 3, B: 0, C: 0, D: 1, E: 0
When you call Present, the runtime shows frame A for 3 vertical blank intervals, then frame D for 1 vertical blank interval, and then frame E until you submit a new presentation. The runtime discards frames C and D.
-Accesses one of the swap-chain's back buffers.
-A zero-based buffer index.
If the swap chain's swap effect is
If the swap chain's swap effect is either
The type of interface used to manipulate the buffer. See remarks.
A reference to a back-buffer interface.
Returns one of the following DXGI_ERROR.
Sets the display state to windowed or full screen.
-A Boolean value that specifies whether to set the display state to windowed or full screen. TRUE for full screen, and
If you pass TRUE to the Fullscreen parameter to set the display state to full screen, you can optionally set this parameter to a reference to an
This methods returns:
When this error is returned, an application can continue to run in windowed mode and try to switch to full-screen mode later.
DXGI may change the display state of a swap chain in response to end user or system requests.
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through SetFullscreenState; that is, do not set the Windowed member of
If a Metro style app calls SetFullscreenState to set the display state to full screen, SetFullscreenState fails with
You cannot call SetFullscreenState on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
For the flip presentation model, after you transition the display state to full screen, you must call ResizeBuffers to ensure that your call to IDXGISwapChain1::Present1 succeeds.
-Get the state associated with full-screen mode.
-A reference to a boolean whose value is either:
A reference to the output target (see
Returns one of the following DXGI_ERROR.
When the swap chain is in full-screen mode, a reference to the target output will be returned and its reference count will be incremented.
-[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
-Returns one of the following DXGI_ERROR.
Changes the swap chain's back buffer size, format, and number of buffers. This should be called when the application window is resized.
-The number of buffers in the swap chain (including all back and front buffers). This number can be different from the number of buffers with which you created the swap chain. This number can't be greater than DXGI_MAX_SWAP_CHAIN_BUFFERS. Set this number to zero to preserve the existing number of buffers in the swap chain. You can't specify greater than two buffers for the flip presentation model.
New width of the back buffer. If you specify zero, DXGI will use the width of the client area of the target window. You can't specify the width as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
New height of the back buffer. If you specify zero, DXGI will use the height of the client area of the target window. You can't specify the height as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
A
A combination of
Returns
You can't resize a swap chain unless you release all outstanding references to its back buffers. You must release all of its direct and indirect references on the back buffers in order for ResizeBuffers to succeed.
Direct references are held by the application after it calls AddRef on a resource.
Indirect references are held by views to a resource, binding a view of the resource to a device context, a command list that used the resource, a command list that used a view to that resource, a command list that executed another command list that used the resource, and so on.
Before you call ResizeBuffers, ensure that the application releases all references (by calling the appropriate number of Release invocations) on the resources, any views to the resource, and any command lists that use either the resources or views, and ensure that neither the resource nor a view is still bound to a device context. You can use
For swap chains that you created with
We recommend that you call ResizeBuffers when a client window is resized (that is, when an application receives a WM_SIZE message).
The only difference between ResizeBuffers in Windows Developer Preview and ResizeBuffers in Windows?7 is with flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set. In Windows Developer Preview, you must call ResizeBuffers to realize a transition between full-screen mode and windowed mode; otherwise, your next call to the Present method fails.
-Resizes the output target.
-A reference to a
Returns a code that indicates success or failure.
ResizeTarget resizes the target window when the swap chain is in windowed mode, and changes the display mode on the target output when the swap chain is in full-screen mode. Therefore, applications can call ResizeTarget to resize the target window (rather than a Microsoft Win32API such as SetWindowPos) without knowledge of the swap chain display mode.
If a Metro style app calls ResizeTarget, it fails with
You cannot call ResizeTarget on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-A reference to the output interface (see
Returns one of the following DXGI_ERROR.
If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-A reference to a
Returns one of the DXGI_ERROR values.
You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
-Gets the number of times that
Returns one of the DXGI_ERROR values.
For info about presentation statistics for a frame, see
[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
-Gets the number of times that
For info about presentation statistics for a frame, see
Describes an adapter (or video card) by using DXGI 1.0.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
Describes an adapter (or video card) using DXGI 1.1.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
A value of the
Describes timing and presentation statistics for a frame.
-You initialize the
You can only use
The values in the PresentCount and PresentRefreshCount members indicate information about when a frame was presented on the display screen. You can use these values to determine whether a glitch occurred. The values in the SyncRefreshCount and SyncQPCTime members indicate timing information that you can use for audio and video synchronization or very precise animation. If the swap chain draws in full-screen mode, these values are based on when the computer booted. - If the swap chain draws in windowed mode, these values are based on when the swap chain is created.
-A value that represents the running total count of times that an image was presented to the monitor since the computer booted.
Note??The number of times that an image was presented to the monitor is not necessarily the same as the number of times that you called
A value that represents the running total count of v-blanks at which the last image was presented to the monitor and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the running total count of v-blanks when the scheduler last sampled the machine time by calling QueryPerformanceCounter and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the high-resolution performance counter timer. This value is the same as the value returned by the QueryPerformanceCounter function.
Reserved. Always returns 0.
Controls the settings of a gamma curve.
-The
A
A
An array of
Controls the gamma capabilities of an adapter.
-To get a list of the capabilities for controlling gamma correction, call
True if scaling and offset operations are supported during gamma correction; otherwise, false.
A value describing the maximum range of the control-point positions.
A value describing the minimum range of the control-point positions.
A value describing the number of control points in the array.
An array of values describing control points; the maximum length of control points is 1025.
Describes a mapped rectangle that is used to access a surface.
-The
A value that describes the width, in bytes, of the surface.
A reference to the image buffer of the surface.
Describes a display mode.
-The following format values are valid for display modes and when you create a bit-block transfer (bitblt) model swap chain. The valid values depend on the feature level that you are working with.
Feature level >= 9.1
Feature level >= 10.0
Feature level >= 11.0
You can pass one of these format values to
Starting with Windows Developer Preview for a flip model swap chain (that is, a swap chain that has the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set in the SwapEffect member of
Because of the relaxed render target creation rules that Direct3D 11 has for back buffers, applications can create a
A value that describes the resolution width. If you specify the width as zero when you call the
A value describing the resolution height. If you specify the height as zero when you call the
A
A
A member of the
A member of the
Describes an output or physical connection between the adapter (video card) and a device.
-The
A string that contains the name of the output device.
A
True if the output is attached to the desktop; otherwise, false.
A member of the
An
Represents a rational number.
-The
An unsigned integer value representing the top of the rational number.
An unsigned integer value representing the bottom of the rational number.
Describes multi-sampling parameters for a resource.
-The default sampler mode, with no anti-aliasing, has a count of 1 and a quality level of 0.
If multi-sample antialiasing is being used, all bound render targets and depth buffers must have the same sample counts and quality levels.
| Differences between Direct3D 10.0 and Direct3D 10.1 and between Direct3D 10.0 and Direct3D 11: Direct3D 10.1 has defined two standard quality levels: Direct3D 11 has defined two standard quality levels: |
?
-The number of multisamples per pixel.
The image quality level. The higher the quality, the lower the performance. The valid range is between zero and one less than the level returned by
For Direct3D 10.1 and Direct3D 11, you can use two special quality level values. For more information about these quality level values, see Remarks.
Represents a handle to a shared resource.
-To create a shared surface, pass a shared-resource handle into the
A handle to a shared resource.
Describes a surface.
-A value describing the surface width.
A value describing the surface height.
A member of the
A member of the
Describes a swap chain.
-In full-screen mode, there is a dedicated front buffer; in windowed mode, the desktop is the front buffer.
If you create a swap chain with one buffer, specifying
For performance information about flipping swap-chain buffers in full-screen application, see Full-Screen Application Performance Hints.
-A
A
A member of the DXGI_USAGE enumerated type that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
A value that describes the number of buffers in the swap chain. When you call
An
A Boolean value that specifies whether the output is in windowed mode. TRUE if the output is in windowed mode; otherwise,
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through
For more information about choosing windowed verses full screen, see
A member of the
A member of the
The
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
An
Sets application-defined data to the object and associates that data with a
A
The size of the object's data.
A reference to the object's data.
Returns one of the DXGI_ERROR values.
SetPrivateData makes a copy of the specified data and stores it with the object.
Private data that SetPrivateData stores in the object occupies the same storage space as private data that is stored by associated Direct3D objects (for example, by a Microsoft Direct3D?11 device through
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is "<unnamed>". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the well-known private data
static const char c_szName[] = "My name";
- hr = pContext->SetPrivateData( You can use
Set an interface in the object's private data.
-A
The interface to set.
Returns one of the following DXGI_ERROR.
This API associates an interface reference with the object.
When the interface is set its reference count is incremented. When the data are overwritten (by calling SPD or SPDI with the same
Get a reference to the object's data.
-A
The size of the data.
Pointer to the data.
Returns one of the following DXGI_ERROR.
If the data returned is a reference to an
Gets the parent of the object.
-The ID of the requested interface.
The address of a reference to the parent object.
Returns one of the DXGI_ERROR values.
Enumerate adapter (video card) outputs.
-The index of the output.
The address of a reference to an
A code that indicates success or failure (see DXGI_ERROR). Will return
When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the reference to the output interface, EnumOutputs increments the output interface's reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.
EnumOutputs first returns the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumOutputs then returns other outputs.
-Gets a DXGI 1.0 description of an adapter (or video card).
-A reference to a
Returns
Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create null ;
- } Checks whether the system supports a device interface for a graphics component.
-The
The user mode driver version of InterfaceName. This is returned only if the interface is supported. This parameter can be
Note??You can use CheckInterfaceSupport only to check whether a Direct3D 10.x interface is supported, and only on Windows Vista SP1 and later versions of the operating system. If you try to use CheckInterfaceSupport to check whether a Direct3D 11.x and later version interface is supported, CheckInterfaceSupport returns
Gets a DXGI 1.0 description of an adapter (or video card).
-Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create null ;
- } An
The
The object returned by the Direct3D create device functions implements the
Returns the adapter for the specified device.
-The address of an
Returns
If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Returns a surface. This method is used internally and you should not call it directly in your application.
-A reference to a
The number of surfaces to create.
A DXGI_USAGE flag that specifies how the surface is expected to be used.
An optional reference to a
The address of an
Returns
The CreateSurface method creates a buffer to exchange data between one or more devices. It is used internally, and you should not directly call it.
The runtime automatically creates an
Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Sets the GPU thread priority.
-A value that specifies the required GPU thread priority. This value must be between -7 and 7, inclusive, where 0 represents normal priority.
Return
The values for the Priority parameter function as follows:
To use the SetGPUThreadPriority method, you should have a comprehensive understanding of GPU scheduling. You should profile your application to ensure that it behaves as intended. If used inappropriately, the SetGPUThreadPriority method can impede rendering speed and result in a poor user experience.
-Gets the GPU thread priority.
-A reference to a variable that receives a value that indicates the current GPU thread priority. The value will be between -7 and 7, inclusive, where 0 represents normal priority.
Return
Returns the adapter for the specified device.
-If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Gets or sets the GPU thread priority.
-Inherited from objects that are tied to the device so that they can retrieve a reference to it.
-Retrieves the device.
-The reference id for the device.
The address of a reference to the device.
A code that indicates success or failure (see DXGI_ERROR).
The type of interface that is returned can be any interface published by the device. For example, it could be an
An
Create a factory by calling CreateDXGIFactory.
Because a Direct3D device can be created without creating a swap chain, you might need to retrieve the factory that is used to create the device in order to create a swap chain.
- This can be accomplished by requesting the
See
Enumerates the adapters (video cards).
-The index of the adapter to enumerate.
The address of a reference to an
Returns
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters then returns other adapters with outputs.
-Allows DXGI to monitor an application's message queue for the alt-enter key sequence (which causes the application to switch from windowed to full screen or vice versa).
-The handle of the window that is to be monitored. This parameter can be
One or more of the following values:
The combination of WindowHandle and Flags informs DXGI to stop monitoring window messages for the previously-associated window.
If the application switches to full-screen mode, DXGI will choose a full-screen resolution to be the smallest supported resolution that is larger or the same size as the current back buffer size.
Applications can make some changes to make the transition from windowed to full screen more efficient. For example, on a WM_SIZE message, the application should release any outstanding swap-chain back buffers, call
While windowed, the application can, if it chooses, restrict the size of its window's client area to sizes to which it is comfortable rendering. A fully flexible application would make no such restriction, but UI elements or other design considerations can, of course, make this flexibility untenable. If the application further chooses to restrict its window's client area to just those that match supported full-screen resolutions, the application can field WM_SIZING, then check against
Applications that want to handle mode changes or Alt+Enter themselves should call MakeWindowAssociation with the
If a Metro style app calls MakeWindowAssociation, it fails with
A Microsoft Win32 application can use MakeWindowAssociation to control full-screen transitions through the Alt+Enter key combination and print screen behavior for full screen. For Metro style apps, because DXGI cannot perform full-screen transitions, Metro style app have no way to control full-screen transitions.
-Get the window through which the user controls the transition to and from full screen.
-A reference to a window handle.
If a Metro style app calls GetWindowAssociation, it fails with
[Starting with Direct3D 11.1, we recommend not to use CreateSwapChain anymore to create a swap chain. Instead, use CreateSwapChainForHwnd, CreateSwapChainForImmersiveWindow, or CreateSwapChainForCompositionSurface depending on how you want to create the swap chain.]
Creates a swap chain.
-
If you attempt to create a swap chain in full-screen mode, and full-screen mode is unavailable, the swap chain will be created in windowed mode and
If the buffer width or the buffer height is zero, the sizes will be inferred from the output window size in the swap-chain description.
Because the target output cannot be chosen explicitly when the swap-chain is created, you should not create a full-screen swap chain. This can reduce presentation performance if the swap chain size and the output window size do not match. Here are two ways to ensure that the sizes match:
If the swap chain is in full-screen mode, before you release it you must use SetFullscreenState to switch it to windowed mode. For more information about releasing a swap chain, see the "Destroying a Swap Chain" section of DXGI Overview.
You can specify
However, to use stereo presentation and to change resize behavior for the flip model, applications must use the IDXGIFactory2::CreateSwapChainForHwnd method. Otherwise, the back-buffer contents implicitly scale to fit the presentation target size; that is, you can't turn off scaling.
Notes for Metro style appsIf a Metro style app calls CreateSwapChain with full screen specified, CreateSwapChain fails.
Metro style apps call the IDXGIFactory2::CreateSwapChainForImmersiveWindow method to create a swap chain.
-Create an adapter interface that represents a software adapter.
-Handle to the software adapter's dll. HMODULE can be obtained with GetModuleHandle or LoadLibrary.
Address of a reference to an adapter (see
A software adapter is a DLL that implements the entirety of a device driver interface, plus emulation, if necessary, of kernel-mode graphics components for Windows. Details on implementing a software adapter can be found in the Windows Vista Driver Development Kit. This is a very complex development task, and is not recommended for general readers.
Calling this method will increment the module's reference count by one. The reference count can be decremented by calling FreeLibrary.
The typical calling scenario is to call LoadLibrary, pass the handle to CreateSoftwareAdapter, then immediately call FreeLibrary on the DLL and forget the DLL's HMODULE. Since the software adapter calls FreeLibrary when it is destroyed, the lifetime of the DLL will now be owned by the adapter, and the application is free of any further consideration of its lifetime.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
To create a factory, call the CreateDXGIFactory1 function.
-Enumerates both adapters (video cards) with or without outputs.
-The index of the adapter to enumerate.
The address of a reference to an
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters1 method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters1 increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters1 first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters1 next returns other adapters with outputs. EnumAdapters1 finally returns adapters without outputs.
-Informs an application of the possible need to re-enumerate adapters.
-IsCurrent returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Informs an application of the possible need to re-enumerate adapters.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Identifies the type of DXGI adapter.
-The
Specifies no flags.
Value always set to 0. This flag is reserved.
Flags that indicate how the back buffers should be rotated to fit the physical rotation of a monitor.
-Unspecified rotation.
Specifies no rotation.
Specifies 90 degrees of rotation.
Specifies 180 degrees of rotation.
Specifies 270 degrees of rotation.
Flags indicating how an image is stretched to fit a given monitor's resolution.
-Unspecified scaling.
Specifies no scaling. The image is centered on the display. This flag is typically used for a fixed-dot-pitch display (such as an LED display).
Specifies stretched scaling.
Flags indicating the method the raster uses to create an image on a surface.
-Scanline order is unspecified.
The image is created from the first scanline to the last without skipping any.
The image is created beginning with the upper field.
The image is created beginning with the lower field.
Status codes that can be returned by DXGI functions.
-Resource data formats which includes fully-typed and typeless formats. There is a list of format modifiers at the bottom of the page, that more fully describes each format type.
-A few formats have additional restrictions.
The following topics provide lists of the formats that particular hardware feature levels support:
For a list of the DirectXMath types that map to
Each enumeration value contains a format modifier which describes the data type.
| Format Modifiers | Description |
|---|---|
| _FLOAT | A floating-point value; 32-bit floating-point formats use IEEE 754 single-precision (s23e8 format): sign bit, 8-bit biased (127) exponent, and 23-bit mantissa. 16-bit floating-point formats use half-precision (s10e5 format): sign bit, 5-bit biased (15) exponent, and 10-bit mantissa. |
| _SINT | Two's complement signed integer. For example, a 3-bit SINT represents the values -4, -3, -2, -1, 0, 1, 2, 3. |
| _SNORM | Signed normalized integer; which is interpreted in a resource as a signed integer, and is interpreted in a shader as a signed normalized floating-point value in the range [-1, 1]. For an 2's complement number, the maximum value is 1.0f (a 5-bit value 01111 maps to 1.0f), and the minimum value is -1.0f (a 5-bit value 10000 maps to -1.0f). In addition, the second-minimum number maps to -1.0f (a 5-bit value 10001 maps to -1.0f). The resulting integer representations are evenly spaced floating-point values in the range (-1.0f...0.0f), and also a complementary set of representations for numbers in the range (0.0f...1.0f). |
| _SRGB | Standard RGB data, which roughly displays colors in a linear ramp of luminosity levels such that an average observer, under average viewing conditions, can view them on an average display. All 0's maps to 0.0f, and all 1's maps to 1.0f. The sequence of unsigned integer encodings between all 0's and all 1's represent a nonlinear progression in the floating-point interpretation of the numbers between 0.0f to 1.0f. For more detail, see the SRGB color standard, IEC 61996-2-1, at IEC (International Electrotechnical Commission). Conversion to or from sRGB space is automatically done by D3DX10 or D3DX9 texture-load functions. If the format has an alpha channel, the alpha data is also stored in sRGB color space. |
| _TYPELESS | Typeless data, with a defined number of bits. Typeless formats are designed for creating typeless resources; that is, a resource whose size is known, but whose data type is not yet fully defined. When a typeless resource is bound to a shader, the application or shader must resolve the format type (which must match the number of bits per component in the typeless format). A typeless format contains one or more subformats; each subformat resolves the data type. For example, in the R32G32B32 group, which defines types for three-component 96-bit data, there is one typeless format and three fully typed subformats. |
| _UINT | Unsigned integer. For instance, a 3-bit UINT represents the values 0, 1, 2, 3, 4, 5, 6, 7. |
| _UNORM | Unsigned normalized integer; which is interpreted in a resource as an unsigned integer, and is interpreted in a shader as an unsigned normalized floating-point value in the range [0, 1]. All 0's maps to 0.0f, and all 1's maps to 1.0f. A sequence of evenly spaced floating-point values from 0.0f to 1.0f are represented. For instance, a 2-bit UNORM represents 0.0f, 1/3, 2/3, and 1.0f. |
?
New Resource FormatsDirect3D 10 offers new data compression formats for compressing high-dynamic range (HDR) lighting data, normal maps and heightfields to a fraction of their original size. These compression types include:
The block compression formats can be used for any of the 2D or 3D texture types ( Texture2D, Texture2DArray, Texture3D, or TextureCube) including mipmap surfaces. The block compression techniques require texture dimensions to be a multiple of 4 (since the implementation compresses on blocks of 4x4 texels). In the texture sampler, compressed formats are always decompressed before texture filtering.
-The format is not known.
A four-component, 128-bit typeless format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit floating-point format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit unsigned-integer format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit signed-integer format that supports 32 bits per channel including alpha. 1
A three-component, 96-bit typeless format that supports 32 bits per color channel.
A three-component, 96-bit floating-point format that supports 32 bits per color channel.
A three-component, 96-bit unsigned-integer format that supports 32 bits per color channel.
A three-component, 96-bit signed-integer format that supports 32 bits per color channel.
A four-component, 64-bit typeless format that supports 16 bits per channel including alpha.
A four-component, 64-bit floating-point format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-integer format that supports 16 bits per channel including alpha.
A two-component, 64-bit typeless format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit floating-point format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit unsigned-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit signed-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit typeless format that supports 32 bits for the red channel, 8 bits for the green channel, and 24 bits are unused.
A 32-bit floating-point component, and two unsigned-integer components (with an additional 32 bits). This format supports 32-bit depth, 8-bit stencil, and 24 bits are unused.
A 32-bit floating-point component, and two typeless components (with an additional 32 bits). This format supports 32-bit red channel, 8 bits are unused, and 24 bits are unused.
A 32-bit typeless component, and two unsigned-integer components (with an additional 32 bits). This format has 32 bits unused, 8 bits for green channel, and 24 bits are unused.
A four-component, 32-bit typeless format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-integer format that supports 10 bits for each color and 2 bits for alpha.
Three partial-precision floating-point numbers encoded into a single 32-bit value (a variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There are no sign bits, and there is a 5-bit biased (15) exponent for each channel, 6-bit mantissa for R and G, and a 5-bit mantissa for B, as shown in the following illustration.
A four-component, 32-bit typeless format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized integer sRGB format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-integer format that supports 8 bits per channel including alpha.
A two-component, 32-bit typeless format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit floating-point format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit unsigned-normalized-integer format that supports 16 bits each for the green and red channels.
A two-component, 32-bit unsigned-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-normalized-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A single-component, 32-bit typeless format that supports 32 bits for the red channel.
A single-component, 32-bit floating-point format that supports 32 bits for depth.
A single-component, 32-bit floating-point format that supports 32 bits for the red channel.
A single-component, 32-bit unsigned-integer format that supports 32 bits for the red channel.
A single-component, 32-bit signed-integer format that supports 32 bits for the red channel.
A two-component, 32-bit typeless format that supports 24 bits for the red channel and 8 bits for the green channel.
A 32-bit z-buffer format that supports 24 bits for depth and 8 bits for stencil.
A 32-bit format, that contains a 24 bit, single-component, unsigned-normalized integer, with an additional typeless 8 bits. This format has 24 bits red channel and 8 bits unused.
A 32-bit format, that contains a 24 bit, single-component, typeless format, with an additional 8 bit unsigned integer component. This format has 24 bits unused and 8 bits green channel.
A two-component, 16-bit typeless format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A single-component, 16-bit typeless format that supports 16 bits for the red channel.
A single-component, 16-bit floating-point format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for depth.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-integer format that supports 16 bits for the red channel.
A single-component, 8-bit typeless format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format for alpha only.
A single-component, 1-bit unsigned-normalized integer format that supports 1 bit for the red channel. 2.
Three partial-precision floating-point numbers encoded into a single 32-bit value all sharing the same 5-bit exponent (variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There is no sign bit, and there is a shared 5-bit biased (15) exponent and a 9-bit mantissa for each channel, as shown in the following illustration. 2.
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the UYVY format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the YUY2 format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A three-component, 16-bit unsigned-normalized-integer format that supports 5 bits for blue, 6 bits for green, and 5 bits for red.
A four-component, 16-bit unsigned-normalized-integer format that supports 5 bits for each color channel and 1-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8 bits unused.
A four-component, 32-bit 2.8-biased fixed-point format that supports 10 bits for each color channel and 2-bit alpha.
A four-component, 32-bit typeless format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit typeless format that supports 8 bits for each color channel, and 8 bits are unused. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each color channel, and 8 bits are unused. 4
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Flags indicating the memory location of a resource.
-The resource is located in video memory.
At least some of the resource is located in CPU memory.
At least some of the resource has been paged out to the hard drive.
Options for swap-chain behavior.
-This enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
Swap chains that you create in full-screen mode with the
Swap chains that you create with the IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForImmersiveWindow, and IDXGIFactory2::CreateSwapChainForCompositionSurface methods are not protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is not set and are protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is set. When swap chains are protected, screen scraping is prevented and, in full-screen mode, presented content is not accessible through the desktop duplication APIs.
-Set this flag to turn off automatic image rotation; that is, do not perform a rotation when transferring the contents of the front buffer to the monitor. Use this flag to avoid a bandwidth penalty when an application expects to handle rotation. This option is valid only during full-screen mode.
Set this flag to enable an application to switch modes by calling
Set this flag to enable an application to render using GDI on a swap chain or a surface. This will allow the application to call
Options for handling pixels in a display surface after calling
This enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
The primary difference between presentation models is how back-buffer contents get to the Desktop Window Manager (DWM) for composition. In the bitblt model, which is used with the
Regardless of whether the flip model is more efficient, an application still might choose the bitblt model for the following reasons:
The bitblt model is the only way to mix GDI and DirectX presentation.
In the flip model, the application must create the swap chain with
Creates a DXGI 1.1 factory that generates objects used to enumerate and specify video graphics settings.
-The globally unique identifier (
Address of a reference to an
Returns
Use a DXGI 1.1 factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the full-screen display mode.
If the CreateDXGIFactory1 function succeeds, the reference count on the
This entry point is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Note??Do not mix the use of DXGI 1.0 (
Creates a DXGI 1.0 factory that generates objects used to enumerate and specify video graphics settings.
-The globally unique identifier (
Address of a reference to an
Returns
Use a DXGI factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the fullscreen display mode.
If the CreateDXGIFactory function succeeds, the reference count on the
Note??Do not mix the use of DXGI 1.0 (
The CreateDXGIFactory function does not exist for Metro style apps. Instead, Metro style apps use the CreateDXGIFactory1 function.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
Gets a DXGI 1.1 description of an adapter (or video card).
-A reference to a
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
Gets a DXGI 1.1 description of an adapter (or video card).
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
An
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
The
Sets the number of frames that the system is allowed to queue for rendering.
-The maximum number of back buffer frames that a driver can queue. The value defaults to 3, but can range from 1 to 16. A value of 0 will reset latency to the default. For multi-head devices, this value is specified per-head.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets the number of frames that the system is allowed to queue for rendering.
-This value is set to the number of frames that can be queued for render. This value defaults to 3, but can range from 1 to 16.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets or sets the number of frames that the system is allowed to queue for rendering.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Using a key, acquires exclusive rendering access to a shared resource.
-The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, acquires exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method will succeed when the device that currently owns the surface calls the
The time-out interval, in milliseconds. This method will return if the interval elapses, and the keyed mutex has not been released using the specified Key. If this value is set to zero, the AcquireSync method will test to see if the keyed mutex has been released and returns immediately. If this value is set to INFINITE, the time-out interval will never elapse.
Return
If the owning device attempted to create another keyed mutex on the same shared resource, AcquireSync returns E_FAIL.
AcquireSync can also return the following DWORD constants. Therefore, you should explicitly check for these constants. If you only use the SUCCEEDED macro on the return value to determine if AcquireSync succeeded, you will not catch these constants.
The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, releases exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method succeeds when the device that currently owns the surface calls the ReleaseSync method using the same value. This value can be any UINT64 value.
Returns
If the device attempted to release a keyed mutex that is not valid or owned by the device, ReleaseSync returns E_FAIL.
The ReleaseSync method releases a lock to a surface that is shared between multiple devices. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
After you call the ReleaseSync method, the shared resource is unset from the rendering pipeline.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
An
To see the outputs available, use
Get a description of the output.
-A reference to the output description (see
Returns a code that indicates success or failure.
[Starting with Direct3D 11.1, we recommend not to use GetDisplayModeList anymore to retrieve the matching display mode. Instead, use IDXGIOutput1::GetDisplayModeList1, which supports stereo display mode.]
Gets the display modes that match the requested format and other input options.
-Returns one of the following DXGI_ERROR. It is rare, but possible, that the display modes available can change immediately after calling this method, in which case
In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.
UINT num = 0;
- [Starting with Direct3D 11.1, we recommend not to use FindClosestMatchingMode anymore to find the display mode that most closely matches the requested display mode. Instead, use IDXGIOutput1::FindClosestMatchingMode1, which supports stereo display mode.]
Finds the display mode that most closely matches the requested display mode.
-Returns one of the following DXGI_ERROR.
FindClosestMatchingMode behaves similarly to the IDXGIOutput1::FindClosestMatchingMode1 except FindClosestMatchingMode considers only the mono display modes. IDXGIOutput1::FindClosestMatchingMode1 considers only stereo modes if you set the Stereo member in the DXGI_MODE_DESC1 structure that pModeToMatch points to, and considers only mono modes if Stereo is not set.
IDXGIOutput1::FindClosestMatchingMode1 returns a matched display-mode set with only stereo modes or only mono modes. - FindClosestMatchingMode behaves as though you specified the input mode as mono.
-Halt a thread until the next vertical blank occurs.
-Returns one of the following DXGI_ERROR.
A vertical blank occurs when the raster moves from the lower right corner to the upper left corner to begin drawing the next frame.
-Takes ownership of an output.
-A reference to the
Set to TRUE to enable other threads or applications to take ownership of the device; otherwise, set to
Returns one of the DXGI_ERROR values.
When you are finished with the output, call
TakeOwnership should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.
Notes for Metro style appsIf a Metro style app uses TakeOwnership, it fails with
Releases ownership of the output.
-If you are not using a swap chain, get access to an output by calling
Gets a description of the gamma-control capabilities.
-A reference to a description of the gamma-control capabilities (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Sets the gamma controls.
-A reference to an array of gamma controls (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Gets the gamma control settings.
-An array of gamma control settings (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Changes the display mode.
-A reference to a surface (see
Returns one of the DXGI_ERROR values.
This method should only be called between
If a Metro style app uses SetDisplaySurface, it fails with
[Starting with Direct3D 11.1, we recommend not to use GetDisplaySurfaceData anymore to retrieve the current display surface. Instead, use IDXGIOutput1::GetDisplaySurfaceData1, which supports stereo display mode.]
Gets a copy of the current display surface.
-Returns one of the DXGI_ERROR values.
Use
Gets statistics about recently rendered frames.
-A reference to frame statistics (see
If this function succeeds, it returns
This API is similar to
Note??Calling this method is only supported while in full-screen mode.
- UINT num = 0;
- DXGI_FORMAT format = DXGI_FORMAT_R32G32B32A32_FLOAT;
- UINT flags = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ... DXGI_MODE_DESC * pDescs = new DXGI_MODE_DESC[num];
- pOutput->GetDisplayModeList( format, flags, &num, pDescs);
-
-
- Get a description of the output.
-Gets a description of the gamma-control capabilities.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets or sets the gamma control settings.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets statistics about recently rendered frames.
-This API is similar to
Note??Calling this method is only supported while in full-screen mode.
-An
To find out what type of memory a resource is currently located in, use
You can retrieve the
[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
-Returns one of the DXGI_ERROR values.
You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-A reference to a usage flag (see DXGI_USAGE). For Direct3D 10, a surface can be used as a shader input or a render-target output.
Returns one of the following DXGI_ERROR.
Set the priority for evicting the resource from memory.
-The priority is one of the following values:
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI for determining how to populate overcommitted memory.
You can set priority levels other than the defined values when appropriate. For example, you can set a resource with a priority level of 0x78000001 to indicate that the resource is slightly above normal.
-Get the eviction priority.
-A reference to the eviction priority, which determines when a resource can be evicted from memory.
The following defined values are possible.
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
-You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-Get or sets the eviction priority.
-The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-The
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
The runtime automatically creates an
Get a description of the surface.
-A reference to the surface description (see
Returns
Get a reference to the data contained in the surface, and deny GPU access to the surface.
-A reference to the surface data (see
CPU read-write flags. These flags can be combined with a logical OR.
Returns
Use
Invalidate the reference to the surface retrieved by
Returns
Get a description of the surface.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
Any object that supports
The runtime automatically creates an
Returns a device context (DC) that allows you to render to a Microsoft DirectX Graphics Infrastructure (DXGI) surface using Windows Graphics Device Interface (GDI).
-A Boolean value that specifies whether to preserve Direct3D contents in the GDI DC. TRUE directs the runtime not to preserve Direct3D contents in the GDI DC; that is, the runtime discards the Direct3D contents.
A reference to an
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
After you use the GetDC method to retrieve a DC, you can render to the DXGI surface by using GDI. The GetDC method readies the surface for GDI rendering and allows inter-operation between DXGI and GDI technologies.
Keep the following in mind when using this method:
You can also call GetDC on the back buffer at index 0 of a swap chain by obtaining an
null ;
- null ;
- ...
- //Setup the device and and swapchain
- g_pSwapChain->GetBuffer(0, __uuidof(null ); Releases the GDI device context (DC) that is associated with the current surface and allows you to use Direct3D to render.
-A reference to a
You can pass a reference to an empty
If this method succeeds, it returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the ReleaseDC method to release the DC and indicate that your application finished all GDI rendering to this surface. You must call the ReleaseDC method before you can use Direct3D to perform additional rendering.
Prior to resizing buffers you must release all outstanding DCs.
-An
You can create a swap chain in several ways. If your application uses Direct3D, create a swap chain when you create a device by
- calling
[Starting with Direct3D 11.1, we recommend not to use Present anymore to present a rendered image. Instead, use IDXGISwapChain1::Present1.]
Presents a rendered image to the user.
-Possible return values include:
Note??The Present method can return either
For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.
Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.
| Differences between Direct3D 9 and Direct3D 10: Specifying |
?
For flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set, a successful presentation unbinds back buffer 0 from the graphics pipeline, except for when you pass the
Suppose the following frames with sync-interval values are queued from oldest (A) to newest (E) before you call Present.
A: 3, B: 0, C: 0, D: 1, E: 0
When you call Present, the runtime shows frame A for 3 vertical blank intervals, then frame D for 1 vertical blank interval, and then frame E until you submit a new presentation. The runtime discards frames C and D.
-Accesses one of the swap-chain's back buffers.
-A zero-based buffer index.
If the swap chain's swap effect is
If the swap chain's swap effect is either
The type of interface used to manipulate the buffer. See remarks.
A reference to a back-buffer interface.
Returns one of the following DXGI_ERROR.
Sets the display state to windowed or full screen.
-A Boolean value that specifies whether to set the display state to windowed or full screen. TRUE for full screen, and
If you pass TRUE to the Fullscreen parameter to set the display state to full screen, you can optionally set this parameter to a reference to an
This methods returns:
When this error is returned, an application can continue to run in windowed mode and try to switch to full-screen mode later.
DXGI may change the display state of a swap chain in response to end user or system requests.
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through SetFullscreenState; that is, do not set the Windowed member of
If a Metro style app calls SetFullscreenState to set the display state to full screen, SetFullscreenState fails with
You cannot call SetFullscreenState on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
For the flip presentation model, after you transition the display state to full screen, you must call ResizeBuffers to ensure that your call to IDXGISwapChain1::Present1 succeeds.
-Get the state associated with full-screen mode.
-A reference to a boolean whose value is either:
A reference to the output target (see
Returns one of the following DXGI_ERROR.
When the swap chain is in full-screen mode, a reference to the target output will be returned and its reference count will be incremented.
-[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
-Returns one of the following DXGI_ERROR.
Changes the swap chain's back buffer size, format, and number of buffers. This should be called when the application window is resized.
-The number of buffers in the swap chain (including all back and front buffers). This number can be different from the number of buffers with which you created the swap chain. This number can't be greater than DXGI_MAX_SWAP_CHAIN_BUFFERS. Set this number to zero to preserve the existing number of buffers in the swap chain. You can't specify greater than two buffers for the flip presentation model.
New width of the back buffer. If you specify zero, DXGI will use the width of the client area of the target window. You can't specify the width as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
New height of the back buffer. If you specify zero, DXGI will use the height of the client area of the target window. You can't specify the height as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
A
A combination of
Returns
You can't resize a swap chain unless you release all outstanding references to its back buffers. You must release all of its direct and indirect references on the back buffers in order for ResizeBuffers to succeed.
Direct references are held by the application after it calls AddRef on a resource.
Indirect references are held by views to a resource, binding a view of the resource to a device context, a command list that used the resource, a command list that used a view to that resource, a command list that executed another command list that used the resource, and so on.
Before you call ResizeBuffers, ensure that the application releases all references (by calling the appropriate number of Release invocations) on the resources, any views to the resource, and any command lists that use either the resources or views, and ensure that neither the resource nor a view is still bound to a device context. You can use
For swap chains that you created with
We recommend that you call ResizeBuffers when a client window is resized (that is, when an application receives a WM_SIZE message).
The only difference between ResizeBuffers in Windows Developer Preview and ResizeBuffers in Windows?7 is with flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set. In Windows Developer Preview, you must call ResizeBuffers to realize a transition between full-screen mode and windowed mode; otherwise, your next call to the Present method fails.
-Resizes the output target.
-A reference to a
Returns a code that indicates success or failure.
ResizeTarget resizes the target window when the swap chain is in windowed mode, and changes the display mode on the target output when the swap chain is in full-screen mode. Therefore, applications can call ResizeTarget to resize the target window (rather than a Microsoft Win32API such as SetWindowPos) without knowledge of the swap chain display mode.
If a Metro style app calls ResizeTarget, it fails with
You cannot call ResizeTarget on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-A reference to the output interface (see
Returns one of the following DXGI_ERROR.
If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-A reference to a
Returns one of the DXGI_ERROR values.
You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
-Gets the number of times that
Returns one of the DXGI_ERROR values.
For info about presentation statistics for a frame, see
[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
-Gets the number of times that
For info about presentation statistics for a frame, see
Describes an adapter (or video card) by using DXGI 1.0.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
Describes an adapter (or video card) using DXGI 1.1.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
A value of the
Describes timing and presentation statistics for a frame.
-You initialize the
You can only use
The values in the PresentCount and PresentRefreshCount members indicate information about when a frame was presented on the display screen. You can use these values to determine whether a glitch occurred. The values in the SyncRefreshCount and SyncQPCTime members indicate timing information that you can use for audio and video synchronization or very precise animation. If the swap chain draws in full-screen mode, these values are based on when the computer booted. - If the swap chain draws in windowed mode, these values are based on when the swap chain is created.
-A value that represents the running total count of times that an image was presented to the monitor since the computer booted.
Note??The number of times that an image was presented to the monitor is not necessarily the same as the number of times that you called
A value that represents the running total count of v-blanks at which the last image was presented to the monitor and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the running total count of v-blanks when the scheduler last sampled the machine time by calling QueryPerformanceCounter and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the high-resolution performance counter timer. This value is the same as the value returned by the QueryPerformanceCounter function.
Reserved. Always returns 0.
Controls the settings of a gamma curve.
-The
A
A
An array of
Controls the gamma capabilities of an adapter.
-To get a list of the capabilities for controlling gamma correction, call
True if scaling and offset operations are supported during gamma correction; otherwise, false.
A value describing the maximum range of the control-point positions.
A value describing the minimum range of the control-point positions.
A value describing the number of control points in the array.
An array of values describing control points; the maximum length of control points is 1025.
Describes a mapped rectangle that is used to access a surface.
-The
A value that describes the width, in bytes, of the surface.
A reference to the image buffer of the surface.
Describes a display mode.
-The following format values are valid for display modes and when you create a bit-block transfer (bitblt) model swap chain. The valid values depend on the feature level that you are working with.
Feature level >= 9.1
Feature level >= 10.0
Feature level >= 11.0
You can pass one of these format values to
Starting with Windows Developer Preview for a flip model swap chain (that is, a swap chain that has the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set in the SwapEffect member of
Because of the relaxed render target creation rules that Direct3D 11 has for back buffers, applications can create a
A value that describes the resolution width. If you specify the width as zero when you call the
A value describing the resolution height. If you specify the height as zero when you call the
A
A
A member of the
A member of the
Describes an output or physical connection between the adapter (video card) and a device.
-The
A string that contains the name of the output device.
A
True if the output is attached to the desktop; otherwise, false.
A member of the
An
Represents a rational number.
-The
An unsigned integer value representing the top of the rational number.
An unsigned integer value representing the bottom of the rational number.
Describes multi-sampling parameters for a resource.
-The default sampler mode, with no anti-aliasing, has a count of 1 and a quality level of 0.
If multi-sample antialiasing is being used, all bound render targets and depth buffers must have the same sample counts and quality levels.
| Differences between Direct3D 10.0 and Direct3D 10.1 and between Direct3D 10.0 and Direct3D 11: Direct3D 10.1 has defined two standard quality levels: Direct3D 11 has defined two standard quality levels: |
?
-The number of multisamples per pixel.
The image quality level. The higher the quality, the lower the performance. The valid range is between zero and one less than the level returned by
For Direct3D 10.1 and Direct3D 11, you can use two special quality level values. For more information about these quality level values, see Remarks.
Represents a handle to a shared resource.
-To create a shared surface, pass a shared-resource handle into the
A handle to a shared resource.
Describes a surface.
-A value describing the surface width.
A value describing the surface height.
A member of the
A member of the
Describes a swap chain.
-In full-screen mode, there is a dedicated front buffer; in windowed mode, the desktop is the front buffer.
If you create a swap chain with one buffer, specifying
For performance information about flipping swap-chain buffers in full-screen application, see Full-Screen Application Performance Hints.
-A
A
A member of the DXGI_USAGE enumerated type that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
A value that describes the number of buffers in the swap chain. When you call
An
A Boolean value that specifies whether the output is in windowed mode. TRUE if the output is in windowed mode; otherwise,
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through
For more information about choosing windowed verses full screen, see
A member of the
A member of the
The
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
An
Sets application-defined data to the object and associates that data with a
A
The size of the object's data.
A reference to the object's data.
Returns one of the DXGI_ERROR values.
SetPrivateData makes a copy of the specified data and stores it with the object.
Private data that SetPrivateData stores in the object occupies the same storage space as private data that is stored by associated Direct3D objects (for example, by a Microsoft Direct3D?11 device through
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is "<unnamed>". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the well-known private data
static const char c_szName[] = "My name";
- hr = pContext->SetPrivateData( You can use
Set an interface in the object's private data.
-A
The interface to set.
Returns one of the following DXGI_ERROR.
This API associates an interface reference with the object.
When the interface is set its reference count is incremented. When the data are overwritten (by calling SPD or SPDI with the same
Get a reference to the object's data.
-A
The size of the data.
Pointer to the data.
Returns one of the following DXGI_ERROR.
If the data returned is a reference to an
Gets the parent of the object.
-The ID of the requested interface.
The address of a reference to the parent object.
Returns one of the DXGI_ERROR values.
Enumerate adapter (video card) outputs.
-The index of the output.
The address of a reference to an
A code that indicates success or failure (see DXGI_ERROR). Will return
When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the reference to the output interface, EnumOutputs increments the output interface's reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.
EnumOutputs first returns the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumOutputs then returns other outputs.
-Gets a DXGI 1.0 description of an adapter (or video card).
-A reference to a
Returns
Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create IDirect3D9Ex interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, "Direct3DCreate9Ex" ); return pD3D9Create9Ex != null ;
- } Checks whether the system supports a device interface for a graphics component.
-The
The user mode driver version of InterfaceName. This is returned only if the interface is supported. This parameter can be
Note??You can use CheckInterfaceSupport only to check whether a Direct3D 10.x interface is supported, and only on Windows Vista SP1 and later versions of the operating system. If you try to use CheckInterfaceSupport to check whether a Direct3D 11.x and later version interface is supported, CheckInterfaceSupport returns
Gets a DXGI 1.0 description of an adapter (or video card).
-Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()
- { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /* Try to create IDirect3D9Ex interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, "Direct3DCreate9Ex" ); return pD3D9Create9Ex != null ;
- } [This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a desktop duplication interface from the
If an application wants to duplicate the entire desktop, it must create a desktop duplication interface on each active output on the desktop. This interface does not provide an explicit way to synchronize the timing of each output image. Instead, the application must use the time stamp of each output, and then determine how to combine the images.
For DuplicateOutput to succeed, you must create pDevice from
If the current mode is a stereo mode, the desktop duplication interface provides the image for the left stereo image only.
By default, only four processes can use a IDXGIOutputDuplication interface at the same time within a single session. A process can have only one desktop duplication interface on a single desktop output; however, that process can have a desktop duplication interface for each output that is part of the desktop.
If DuplicateOutput fails with
An
To see the outputs available, use
Get a description of the output.
-A reference to the output description (see
Returns a code that indicates success or failure.
[Starting with Direct3D 11.1, we recommend not to use GetDisplayModeList anymore to retrieve the matching display mode. Instead, use
Gets the display modes that match the requested format and other input options.
-Returns one of the following DXGI_ERROR. It is rare, but possible, that the display modes available can change immediately after calling this method, in which case
In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.
UINT num = 0;
- [Starting with Direct3D 11.1, we recommend not to use FindClosestMatchingMode anymore to find the display mode that most closely matches the requested display mode. Instead, use
Finds the display mode that most closely matches the requested display mode.
-Returns one of the following DXGI_ERROR.
FindClosestMatchingMode behaves similarly to the
Halt a thread until the next vertical blank occurs.
-Returns one of the following DXGI_ERROR.
A vertical blank occurs when the raster moves from the lower right corner to the upper left corner to begin drawing the next frame.
-Takes ownership of an output.
-A reference to the
Set to TRUE to enable other threads or applications to take ownership of the device; otherwise, set to
Returns one of the DXGI_ERROR values.
When you are finished with the output, call
TakeOwnership should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.
Notes for Metro style appsIf a Metro style app uses TakeOwnership, it fails with
Releases ownership of the output.
-If you are not using a swap chain, get access to an output by calling
Gets a description of the gamma-control capabilities.
-A reference to a description of the gamma-control capabilities (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Sets the gamma controls.
-A reference to an array of gamma controls (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Gets the gamma control settings.
-An array of gamma control settings (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
-Changes the display mode.
-A reference to a surface (see
Returns one of the DXGI_ERROR values.
This method should only be called between
If a Metro style app uses SetDisplaySurface, it fails with
[Starting with Direct3D 11.1, we recommend not to use GetDisplaySurfaceData anymore to retrieve the current display surface. Instead, use
Gets a copy of the current display surface.
-Returns one of the DXGI_ERROR values.
Use
Gets statistics about recently rendered frames.
-A reference to frame statistics (see
If this function succeeds, it returns
This API is similar to
Note??Calling this method is only supported while in full-screen mode.
- UINT num = 0;
- DXGI_FORMAT format = DXGI_FORMAT_R32G32B32A32_FLOAT;
- UINT flags = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ... DXGI_MODE_DESC * pDescs = new DXGI_MODE_DESC[num];
- pOutput->GetDisplayModeList( format, flags, &num, pDescs);
-
-
- Get a description of the output.
-Gets a description of the gamma-control capabilities.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets or sets the gamma control settings.
-
Note??Calling this method is only supported while in full-screen mode.
-Gets statistics about recently rendered frames.
-This API is similar to
Note??Calling this method is only supported while in full-screen mode.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the display modes that match the requested format and other input options.
-A
A combination of DXGI_ENUM_MODES-typed values that are combined by using a bitwise OR operation. The resulting value specifies options for display modes to include. You must specify
GetDisplayModeList1 is updated from GetDisplayModeList to return a list of
The GetDisplayModeList1 method does not enumerate stereo modes unless you specify the
In general, when you switch from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth, and refresh rate of the swap chain. To exercise more control over the display mode, use GetDisplayModeList1 to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
The following example code shows that you need to call GetDisplayModeList1 twice. First call GetDisplayModeList1 to get the number of modes available, and second call GetDisplayModeList1 to return a description of the modes.
UINT num = 0;
- [This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the display modes that match the requested format and other input options.
-A
A combination of DXGI_ENUM_MODES-typed values that are combined by using a bitwise OR operation. The resulting value specifies options for display modes to include. You must specify
A reference to a variable that receives the number of display modes that GetDisplayModeList1 returns in the memory block to which pDesc points. Set pDesc to
A reference to a list of display modes; set to
Returns one of the error codes described in the DXGI_ERROR topic. It is rare, but possible, that the display modes available can change immediately after calling this method, in which case
GetDisplayModeList1 is updated from GetDisplayModeList to return a list of
The GetDisplayModeList1 method does not enumerate stereo modes unless you specify the
In general, when you switch from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth, and refresh rate of the swap chain. To exercise more control over the display mode, use GetDisplayModeList1 to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
The following example code shows that you need to call GetDisplayModeList1 twice. First call GetDisplayModeList1 to get the number of modes available, and second call GetDisplayModeList1 to return a description of the modes.
UINT num = 0;
- [This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Finds the display mode that most closely matches the requested display mode.
-A reference to the
A reference to the
A reference to the Direct3D device interface. If this parameter is
Returns one of the error codes described in the DXGI_ERROR topic.
Direct3D devices require UNORM formats.
FindClosestMatchingMode1 finds the closest matching available display mode to the mode that you specify in pModeToMatch.
If you set the Stereo member in the
FindClosestMatchingMode1 resolves similarly ranked members of display modes (that is, all specified, or all unspecified, and so on) in the following order:
When FindClosestMatchingMode1 determines the closest value for a particular member, it uses previously matched members to filter the display mode list choices, and ignores other members. For example, when FindClosestMatchingMode1 matches Resolution, it already filtered the display mode list by a certain ScanlineOrdering, Scaling, and Format, while it ignores RefreshRate. This ordering doesn't define the absolute ordering for every usage scenario of FindClosestMatchingMode1, because the application can choose some values initially, which effectively changes the order of resolving members.
FindClosestMatchingMode1 matches members of the display mode one at a time, generally in a specified order.
If a member is unspecified, FindClosestMatchingMode1 gravitates toward the values for the desktop related to this output. If this output is not part of the desktop, FindClosestMatchingMode1 uses the default desktop output to find values. If an application uses a fully unspecified display mode, FindClosestMatchingMode1 typically returns a display mode that matches the desktop settings for this output. Because unspecified members are lower priority than specified members, FindClosestMatchingMode1 resolves unspecified members later than specified members.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the display surface (front buffer) to a user-provided resource.
-A reference to a resource interface that represents the resource to which GetDisplaySurfaceData1 copies the display surface.
Returns one of the error codes described in the DXGI_ERROR topic.
GetDisplaySurfaceData1 is similar to
GetDisplaySurfaceData1 returns an error if the input resource is not a 2D texture (represented by the
The original
You can call GetDisplaySurfaceData1 only when an output is in full-screen mode. If GetDisplaySurfaceData1 succeeds, it fills the destination resource.
Use
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a desktop duplication interface from the
DuplicateOutput returns:
If an application wants to duplicate the entire desktop, it must create a desktop duplication interface on each active output on the desktop. This interface does not provide an explicit way to synchronize the timing of each output image. Instead, the application must use the time stamp of each output, and then determine how to combine the images.
For DuplicateOutput to succeed, you must create pDevice from
If the current mode is a stereo mode, the desktop duplication interface provides the image for the left stereo image only.
By default, only four processes can use a IDXGIOutputDuplication interface at the same time within a single session. A process can have only one desktop duplication interface on a single desktop output; however, that process can have a desktop duplication interface for each output that is part of the desktop.
If DuplicateOutput fails with
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
The
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
Any object that supports
The runtime automatically creates an
You can call the
The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
Any object that supports
The runtime automatically creates an
The
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
The runtime automatically creates an
Inherited from objects that are tied to the device so that they can retrieve a reference to it.
-Retrieves the device.
-The reference id for the device.
The address of a reference to the device.
A code that indicates success or failure (see DXGI_ERROR).
The type of interface that is returned can be any interface published by the device. For example, it could be an
Get a description of the surface.
-A reference to the surface description (see
Returns
Get a reference to the data contained in the surface, and deny GPU access to the surface.
-A reference to the surface data (see
CPU read-write flags. These flags can be combined with a logical OR.
Returns
Use
Invalidate the reference to the surface retrieved by
Returns
Get a description of the surface.
-Returns a device context (DC) that allows you to render to a Microsoft DirectX Graphics Infrastructure (DXGI) surface using Windows Graphics Device Interface (GDI).
-A Boolean value that specifies whether to preserve Direct3D contents in the GDI DC. TRUE directs the runtime not to preserve Direct3D contents in the GDI DC; that is, the runtime discards the Direct3D contents.
A reference to an
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
After you use the GetDC method to retrieve a DC, you can render to the DXGI surface by using GDI. The GetDC method readies the surface for GDI rendering and allows inter-operation between DXGI and GDI technologies.
Keep the following in mind when using this method:
You can also call GetDC on the back buffer at index 0 of a swap chain by obtaining an
null ;
- null ;
- ...
- //Setup the device and and swapchain
- g_pSwapChain->GetBuffer(0, __uuidof(null ); Releases the GDI device context (DC) that is associated with the current surface and allows you to use Direct3D to render.
-A reference to a
You can pass a reference to an empty
If this method succeeds, it returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the ReleaseDC method to release the DC and indicate that your application finished all GDI rendering to this surface. You must call the ReleaseDC method before you can use Direct3D to perform additional rendering.
Prior to resizing buffers you must release all outstanding DCs.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the parent resource and subresource index that support a subresource surface.
-The globally unique identifier (
A reference to a buffer that receives a reference to the parent resource object for the subresource surface.
A reference to a variable that receives the index of the subresource surface.
Returns
For subresource surface objects that the
Current objects that implement
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a handle to a shared resource. You can then use the returned handle with multiple Direct3D devices.
-CreateSharedHandle only returns the NT handle when you created the resource as shared and specified that it uses NT handles (that is, you set the
You can pass the handle that CreateSharedHandle returns in a call to the
Because the handle that CreateSharedHandle returns is an NT handle, you can use the handle with CloseHandle, DuplicateHandle, and so on. You can call CreateSharedHandle only once for a shared resource; later calls fail. If you need more handles to the same shared resource, call DuplicateHandle. When you no longer need the shared resource handle, call CloseHandle to close the handle, in order to avoid memory leaks.
If you pass a name for the resource to lpName when you call CreateSharedHandle to share the resource, you can subsequently pass this name in a call to the
If you created the resource as shared and did not specify that it uses NT handles, you cannot use CreateSharedHandle to get a handle for sharing because CreateSharedHandle will fail.
-An
To find out what type of memory a resource is currently located in, use
You can retrieve the
[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use
Gets the handle to a shared resource.
-Returns one of the DXGI_ERROR values.
You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-A reference to a usage flag (see DXGI_USAGE). For Direct3D 10, a surface can be used as a shader input or a render-target output.
Returns one of the following DXGI_ERROR.
Set the priority for evicting the resource from memory.
-The priority is one of the following values:
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI for determining how to populate overcommitted memory.
You can set priority levels other than the defined values when appropriate. For example, you can set a resource with a priority level of 0x78000001 to indicate that the resource is slightly above normal.
-Get the eviction priority.
-A reference to the eviction priority, which determines when a resource can be evicted from memory.
The following defined values are possible.
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use
Gets the handle to a shared resource.
-You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
-Get the expected resource usage.
-Get or sets the eviction priority.
-The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a subresource surface object.
-The index of the subresource surface object to enumerate.
The address of a reference to a
Returns
A subresource is a valid surface if the original resource would have been a valid surface had its array size been equal to 1.
Subresource surface objects implement the
CreateSubresourceSurface creates a subresource surface that is based on the resource interface on which CreateSubresourceSurface is called. For example, if the original resource interface object is a 2D texture, the created subresource surface is also a 2D texture.
You can use CreateSubresourceSurface to create parts of a stereo resource so you can use Direct2D on either the left or right part of the stereo resource.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a handle to a shared resource. You can then use the returned handle with multiple Direct3D devices.
-A reference to a
Set this parameter to
The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for the resource. Set this member to
The requested access rights to the resource. In addition to the generic access rights, DXGI defines the following values:
You can combine these values by using a bitwise OR operation.
The name of the resource to share. The name is limited to MAX_PATH characters. Name comparison is case sensitive. You will need the resource name if you call the
If lpName matches the name of an existing resource, CreateSharedHandle fails with
The name can have a "Global\" or "Local\" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\). For more information, see Kernel Object Namespaces. Fast user switching is implemented using Terminal Services sessions. Kernel object names must follow the guidelines outlined for Terminal Services so that applications can support multiple users.
The object can be created in a private namespace. For more information, see Object Namespaces.
A reference to a variable that receives the NT HANDLE value to the resource to share. You can use this handle in calls to access the resource.
CreateSharedHandle only returns the NT handle when you created the resource as shared and specified that it uses NT handles (that is, you set the
You can pass the handle that CreateSharedHandle returns in a call to the
Because the handle that CreateSharedHandle returns is an NT handle, you can use the handle with CloseHandle, DuplicateHandle, and so on. You can call CreateSharedHandle only once for a shared resource; later calls fail. If you need more handles to the same shared resource, call DuplicateHandle. When you no longer need the shared resource handle, call CloseHandle to close the handle, in order to avoid memory leaks.
If you pass a name for the resource to lpName when you call CreateSharedHandle to share the resource, you can subsequently pass this name in a call to the
If you created the resource as shared and did not specify that it uses NT handles, you cannot use CreateSharedHandle to get a handle for sharing because CreateSharedHandle will fail.
-[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Closes the surface draw operation.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Closes the surface draw operation.
-If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Closes the surface draw operation.
-If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Closes the surface draw operation.
-[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Invalidates a specific region of the shared surface for drawing.
-The region of the surface to invalidate.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Provides the implementation of a large (greater than the screen size) shared surface for DirectX drawing.
-This interface provides the native implementation of the Windows::UI::Xaml::Media::Imaging::VirtualSurfaceImageSource Windows runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_vsisNative; - // ... - IInspectable* vsisInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(virtualSurfaceImageSource); - vsisInspectable->QueryInterface(__uuidof( ), (void **)&m_vsisNative)
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Provides an interface for the implementation of drawing behaviors when a VirtualSurfaceImageSource requests an update.
-This interface is implemented by the developer to provide specific drawing behaviors for updates to a VirtualSurfaceImageSource. Classes that implement this interface are provided to the
An
The
The object returned by the Direct3D create device functions implements the
Returns the adapter for the specified device.
-The address of an
Returns
If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Returns a surface. This method is used internally and you should not call it directly in your application.
-A reference to a
The number of surfaces to create.
A DXGI_USAGE flag that specifies how the surface is expected to be used.
An optional reference to a
The address of an
Returns
The CreateSurface method creates a buffer to exchange data between one or more devices. It is used internally, and you should not directly call it.
The runtime automatically creates an
Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Gets the residency status of an array of resources.
-An array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
-Sets the GPU thread priority.
-A value that specifies the required GPU thread priority. This value must be between -7 and 7, inclusive, where 0 represents normal priority.
Return
The values for the Priority parameter function as follows:
To use the SetGPUThreadPriority method, you should have a comprehensive understanding of GPU scheduling. You should profile your application to ensure that it behaves as intended. If used inappropriately, the SetGPUThreadPriority method can impede rendering speed and result in a poor user experience.
-Gets the GPU thread priority.
-A reference to a variable that receives a value that indicates the current GPU thread priority. The value will be between -7 and 7, inclusive, where 0 represents normal priority.
Return
Returns the adapter for the specified device.
-If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
-Gets or sets the GPU thread priority.
-An
Create a factory by calling CreateDXGIFactory.
Because a Direct3D device can be created without creating a swap chain, you might need to retrieve the factory that is used to create the device in order to create a swap chain.
- This can be accomplished by requesting the
See
Enumerates the adapters (video cards).
-The index of the adapter to enumerate.
The address of a reference to an
Returns
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters then returns other adapters with outputs.
-Allows DXGI to monitor an application's message queue for the alt-enter key sequence (which causes the application to switch from windowed to full screen or vice versa).
-The handle of the window that is to be monitored. This parameter can be
One or more of the following values:
The combination of WindowHandle and Flags informs DXGI to stop monitoring window messages for the previously-associated window.
If the application switches to full-screen mode, DXGI will choose a full-screen resolution to be the smallest supported resolution that is larger or the same size as the current back buffer size.
Applications can make some changes to make the transition from windowed to full screen more efficient. For example, on a WM_SIZE message, the application should release any outstanding swap-chain back buffers, call
While windowed, the application can, if it chooses, restrict the size of its window's client area to sizes to which it is comfortable rendering. A fully flexible application would make no such restriction, but UI elements or other design considerations can, of course, make this flexibility untenable. If the application further chooses to restrict its window's client area to just those that match supported full-screen resolutions, the application can field WM_SIZING, then check against
Applications that want to handle mode changes or Alt+Enter themselves should call MakeWindowAssociation with the
If a Metro style app calls MakeWindowAssociation, it fails with
A Microsoft Win32 application can use MakeWindowAssociation to control full-screen transitions through the Alt+Enter key combination and print screen behavior for full screen. For Metro style apps, because DXGI cannot perform full-screen transitions, Metro style app have no way to control full-screen transitions.
-Get the window through which the user controls the transition to and from full screen.
-A reference to a window handle.
If a Metro style app calls GetWindowAssociation, it fails with
[Starting with Direct3D 11.1, we recommend not to use CreateSwapChain anymore to create a swap chain. Instead, use CreateSwapChainForHwnd, CreateSwapChainForImmersiveWindow, or CreateSwapChainForCompositionSurface depending on how you want to create the swap chain.]
Creates a swap chain.
-
If you attempt to create a swap chain in full-screen mode, and full-screen mode is unavailable, the swap chain will be created in windowed mode and
If the buffer width or the buffer height is zero, the sizes will be inferred from the output window size in the swap-chain description.
Because the target output cannot be chosen explicitly when the swap-chain is created, you should not create a full-screen swap chain. This can reduce presentation performance if the swap chain size and the output window size do not match. Here are two ways to ensure that the sizes match:
If the swap chain is in full-screen mode, before you release it you must use SetFullscreenState to switch it to windowed mode. For more information about releasing a swap chain, see the "Destroying a Swap Chain" section of DXGI Overview.
You can specify
However, to use stereo presentation and to change resize behavior for the flip model, applications must use the
If a Metro style app calls CreateSwapChain with full screen specified, CreateSwapChain fails.
Metro style apps call the IDXGIFactory2::CreateSwapChainForImmersiveWindow method to create a swap chain.
-Create an adapter interface that represents a software adapter.
-Handle to the software adapter's dll. HMODULE can be obtained with GetModuleHandle or LoadLibrary.
Address of a reference to an adapter (see
A software adapter is a DLL that implements the entirety of a device driver interface, plus emulation, if necessary, of kernel-mode graphics components for Windows. Details on implementing a software adapter can be found in the Windows Vista Driver Development Kit. This is a very complex development task, and is not recommended for general readers.
Calling this method will increment the module's reference count by one. The reference count can be decremented by calling FreeLibrary.
The typical calling scenario is to call LoadLibrary, pass the handle to CreateSoftwareAdapter, then immediately call FreeLibrary on the DLL and forget the DLL's HMODULE. Since the software adapter calls FreeLibrary when it is destroyed, the lifetime of the DLL will now be owned by the adapter, and the application is free of any further consideration of its lifetime.
-The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
To create a factory, call the CreateDXGIFactory1 function.
-Enumerates both adapters (video cards) with or without outputs.
-The index of the adapter to enumerate.
The address of a reference to an
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters1 method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters1 increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters1 first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters1 next returns other adapters with outputs. EnumAdapters1 finally returns adapters without outputs.
-Informs an application of the possible need to re-enumerate adapters.
-IsCurrent returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Informs an application of the possible need to re-enumerate adapters.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
-Identifies the type of DXGI adapter.
-The
Specifies no flags.
Value always set to 0. This flag is reserved.
Specifies a software adapter.
Direct3D 11:??This enumeration value is supported starting with Windows Developer Preview.[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies the alpha value, transparency behavior, of a surface.
-For more information about alpha mode, see
Indicates that the transparency behavior is not specified.
Indicates that the transparency behavior is premultiplied. Each color is first scaled by the alpha value. The alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. If a color channel value in a premultiplied format is greater than the alpha channel, the standard source-over blending math results in an additive blend.
Indicates that the transparency behavior is not premultiplied. The alpha channel indicates the transparency of the color.
Indicates to ignore the transparency behavior.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies the granularity at which the graphics processing unit (GPU) can be preempted from performing its current compute task.
-You call the
Indicates the preemption granularity as a compute packet.
Indicates the preemption granularity as a dispatch (for example, a call to the
Indicates the preemption granularity as a thread group. A thread group is a part of a dispatch.
Indicates the preemption granularity as a thread in a thread group. A thread is a part of a thread group.
Indicates the preemption granularity as a compute instruction in a thread.
Flags that indicate how the back buffers should be rotated to fit the physical rotation of a monitor.
-Unspecified rotation.
Specifies no rotation.
Specifies 90 degrees of rotation.
Specifies 180 degrees of rotation.
Specifies 270 degrees of rotation.
Flags indicating how an image is stretched to fit a given monitor's resolution.
-Unspecified scaling.
Specifies no scaling. The image is centered on the display. This flag is typically used for a fixed-dot-pitch display (such as an LED display).
Specifies stretched scaling.
Flags indicating the method the raster uses to create an image on a surface.
-Scanline order is unspecified.
The image is created from the first scanline to the last without skipping any.
The image is created beginning with the upper field.
The image is created beginning with the lower field.
Status codes that can be returned by DXGI functions.
-Resource data formats which includes fully-typed and typeless formats. There is a list of format modifiers at the bottom of the page, that more fully describes each format type.
-A few formats have additional restrictions.
The following topics provide lists of the formats that particular hardware feature levels support:
For a list of the DirectXMath types that map to
Each enumeration value contains a format modifier which describes the data type.
| Format Modifiers | Description |
|---|---|
| _FLOAT | A floating-point value; 32-bit floating-point formats use IEEE 754 single-precision (s23e8 format): sign bit, 8-bit biased (127) exponent, and 23-bit mantissa. 16-bit floating-point formats use half-precision (s10e5 format): sign bit, 5-bit biased (15) exponent, and 10-bit mantissa. |
| _SINT | Two's complement signed integer. For example, a 3-bit SINT represents the values -4, -3, -2, -1, 0, 1, 2, 3. |
| _SNORM | Signed normalized integer; which is interpreted in a resource as a signed integer, and is interpreted in a shader as a signed normalized floating-point value in the range [-1, 1]. For an 2's complement number, the maximum value is 1.0f (a 5-bit value 01111 maps to 1.0f), and the minimum value is -1.0f (a 5-bit value 10000 maps to -1.0f). In addition, the second-minimum number maps to -1.0f (a 5-bit value 10001 maps to -1.0f). The resulting integer representations are evenly spaced floating-point values in the range (-1.0f...0.0f), and also a complementary set of representations for numbers in the range (0.0f...1.0f). |
| _SRGB | Standard RGB data, which roughly displays colors in a linear ramp of luminosity levels such that an average observer, under average viewing conditions, can view them on an average display. All 0's maps to 0.0f, and all 1's maps to 1.0f. The sequence of unsigned integer encodings between all 0's and all 1's represent a nonlinear progression in the floating-point interpretation of the numbers between 0.0f to 1.0f. For more detail, see the SRGB color standard, IEC 61996-2-1, at IEC (International Electrotechnical Commission). Conversion to or from sRGB space is automatically done by D3DX10 or D3DX9 texture-load functions. If the format has an alpha channel, the alpha data is also stored in sRGB color space. |
| _TYPELESS | Typeless data, with a defined number of bits. Typeless formats are designed for creating typeless resources; that is, a resource whose size is known, but whose data type is not yet fully defined. When a typeless resource is bound to a shader, the application or shader must resolve the format type (which must match the number of bits per component in the typeless format). A typeless format contains one or more subformats; each subformat resolves the data type. For example, in the R32G32B32 group, which defines types for three-component 96-bit data, there is one typeless format and three fully typed subformats. |
| _UINT | Unsigned integer. For instance, a 3-bit UINT represents the values 0, 1, 2, 3, 4, 5, 6, 7. |
| _UNORM | Unsigned normalized integer; which is interpreted in a resource as an unsigned integer, and is interpreted in a shader as an unsigned normalized floating-point value in the range [0, 1]. All 0's maps to 0.0f, and all 1's maps to 1.0f. A sequence of evenly spaced floating-point values from 0.0f to 1.0f are represented. For instance, a 2-bit UNORM represents 0.0f, 1/3, 2/3, and 1.0f. |
?
New Resource FormatsDirect3D 10 offers new data compression formats for compressing high-dynamic range (HDR) lighting data, normal maps and heightfields to a fraction of their original size. These compression types include:
The block compression formats can be used for any of the 2D or 3D texture types ( Texture2D, Texture2DArray, Texture3D, or TextureCube) including mipmap surfaces. The block compression techniques require texture dimensions to be a multiple of 4 (since the implementation compresses on blocks of 4x4 texels). In the texture sampler, compressed formats are always decompressed before texture filtering.
-The format is not known.
A four-component, 128-bit typeless format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit floating-point format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit unsigned-integer format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit signed-integer format that supports 32 bits per channel including alpha. 1
A three-component, 96-bit typeless format that supports 32 bits per color channel.
A three-component, 96-bit floating-point format that supports 32 bits per color channel.
A three-component, 96-bit unsigned-integer format that supports 32 bits per color channel.
A three-component, 96-bit signed-integer format that supports 32 bits per color channel.
A four-component, 64-bit typeless format that supports 16 bits per channel including alpha.
A four-component, 64-bit floating-point format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-integer format that supports 16 bits per channel including alpha.
A two-component, 64-bit typeless format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit floating-point format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit unsigned-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit signed-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit typeless format that supports 32 bits for the red channel, 8 bits for the green channel, and 24 bits are unused.
A 32-bit floating-point component, and two unsigned-integer components (with an additional 32 bits). This format supports 32-bit depth, 8-bit stencil, and 24 bits are unused.
A 32-bit floating-point component, and two typeless components (with an additional 32 bits). This format supports 32-bit red channel, 8 bits are unused, and 24 bits are unused.
A 32-bit typeless component, and two unsigned-integer components (with an additional 32 bits). This format has 32 bits unused, 8 bits for green channel, and 24 bits are unused.
A four-component, 32-bit typeless format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-integer format that supports 10 bits for each color and 2 bits for alpha.
Three partial-precision floating-point numbers encoded into a single 32-bit value (a variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There are no sign bits, and there is a 5-bit biased (15) exponent for each channel, 6-bit mantissa for R and G, and a 5-bit mantissa for B, as shown in the following illustration.
A four-component, 32-bit typeless format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized integer sRGB format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-integer format that supports 8 bits per channel including alpha.
A two-component, 32-bit typeless format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit floating-point format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit unsigned-normalized-integer format that supports 16 bits each for the green and red channels.
A two-component, 32-bit unsigned-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-normalized-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A single-component, 32-bit typeless format that supports 32 bits for the red channel.
A single-component, 32-bit floating-point format that supports 32 bits for depth.
A single-component, 32-bit floating-point format that supports 32 bits for the red channel.
A single-component, 32-bit unsigned-integer format that supports 32 bits for the red channel.
A single-component, 32-bit signed-integer format that supports 32 bits for the red channel.
A two-component, 32-bit typeless format that supports 24 bits for the red channel and 8 bits for the green channel.
A 32-bit z-buffer format that supports 24 bits for depth and 8 bits for stencil.
A 32-bit format, that contains a 24 bit, single-component, unsigned-normalized integer, with an additional typeless 8 bits. This format has 24 bits red channel and 8 bits unused.
A 32-bit format, that contains a 24 bit, single-component, typeless format, with an additional 8 bit unsigned integer component. This format has 24 bits unused and 8 bits green channel.
A two-component, 16-bit typeless format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A single-component, 16-bit typeless format that supports 16 bits for the red channel.
A single-component, 16-bit floating-point format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for depth.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-integer format that supports 16 bits for the red channel.
A single-component, 8-bit typeless format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format for alpha only.
A single-component, 1-bit unsigned-normalized integer format that supports 1 bit for the red channel. 2.
Three partial-precision floating-point numbers encoded into a single 32-bit value all sharing the same 5-bit exponent (variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There is no sign bit, and there is a shared 5-bit biased (15) exponent and a 9-bit mantissa for each channel, as shown in the following illustration. 2.
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the UYVY format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the YUY2 format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A three-component, 16-bit unsigned-normalized-integer format that supports 5 bits for blue, 6 bits for green, and 5 bits for red.
A four-component, 16-bit unsigned-normalized-integer format that supports 5 bits for each color channel and 1-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8 bits unused.
A four-component, 32-bit 2.8-biased fixed-point format that supports 10 bits for each color channel and 2-bit alpha.
A four-component, 32-bit typeless format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit typeless format that supports 8 bits for each color channel, and 8 bits are unused. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each color channel, and 8 bits are unused. 4
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Most common YUV 4:4:4 video resource format. Valid view formats for this video resource format are
10-bit per channel packed YUV 4:4:4 video resource format. Valid view formats for this video resource format are
16-bit per channel packed YUV 4:4:4 video resource format. Valid view formats for this video resource format are
Most common YUV 4:2:0 video resource format. Valid luminance data view formats for this video resource format are
10-bit per channel planar YUV 4:2:0 video resource format. Valid luminance data view formats for this video resource format are
16-bit per channel planar YUV 4:2:0 video resource format. Valid luminance data view formats for this video resource format are
8-bit per channel planar YUV 4:2:0 video resource format. This format is subsampled where each pixel has its own Y value, but each 2x2 pixel block shares a single U and V value. The runtime requires that the width and height of all resources that are created with this format are multiples of 2. The runtime also requires that the left, right, top, and bottom members of any
Most common YUV 4:2:2 video resource format. Valid view formats for this video resource format are
A unique valid view format for this video resource format is
10-bit per channel packed YUV 4:2:2 video resource format. Valid view formats for this video resource format are
16-bit per channel packed YUV 4:2:2 video resource format. Valid view formats for this video resource format are
Most common planar YUV 4:1:1 video resource format. Valid luminance data view formats for this video resource format are
4-bit palletized YUV format that is commonly used for DVD subpicture.
Direct3D 11:??This value is not supported until Windows Developer Preview.4-bit palletized YUV format that is commonly used for DVD subpicture.
Direct3D 11:??This value is not supported until Windows Developer Preview.8-bit palletized format that is used for palletized RGB data when the processor processes ISDB-T data and for palletized YUV data when the processor processes BluRay data.
Direct3D 11:??This value is not supported until Windows Developer Preview.8-bit palletized format with 8 bits of alpha that is used for palletized YUV data when the processor processes BluRay data.
Direct3D 11:??This value is not supported until Windows Developer Preview.A four-component, 16-bit unsigned-normalized integer format that supports 4 bits for each channel including alpha.
Direct3D 11:??This value is not supported until Windows Developer Preview.[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies the granularity at which the graphics processing unit (GPU) can be preempted from performing its current graphics rendering task.
-You call the
The following figure shows granularity of graphics rendering tasks.
-Indicates the preemption granularity as a DMA buffer.
Indicates the preemption granularity as a graphics primitive. A primitive is a section in a DMA buffer and can be a group of triangles.
Indicates the preemption granularity as a triangle. A triangle is a part of a primitive.
Indicates the preemption granularity as a pixel. A pixel is a part of a triangle.
Indicates the preemption granularity as a graphics instruction. A graphics instruction operates on a pixel.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies the importance of a resource?s content when you call the
Priority determines how likely the operating system is to discard an offered resource. Resources offered with lower priority are discarded first.
-Flags indicating the memory location of a resource.
-The resource is located in video memory.
At least some of the resource is located in CPU memory.
At least some of the resource has been paged out to the hard drive.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies resize behavior when the back-buffer size does not match the size of the target output.
-The
Directs DXGI to make the back-buffer contents scale to fit the presentation target size. This is the implicit behavior of DXGI when you call the
Directs DXGI to make the back-buffer contents appear without any scaling when the presentation target size is not equal to the back-buffer size. The top edges of the back buffer and presentation target are aligned together. If the WS_EX_LAYOUTRTL style is associated with the
This value specifies that all target areas outside the back buffer of a swap chain are filled with the background color that you specify in a call to
Options for swap-chain behavior.
-This enumeration is used by the
This enumeration is also used by the
Swap chains that you create in full-screen mode with the
Swap chains that you create with the
Set this flag to turn off automatic image rotation; that is, do not perform a rotation when transferring the contents of the front buffer to the monitor. Use this flag to avoid a bandwidth penalty when an application expects to handle rotation. This option is valid only during full-screen mode.
Set this flag to enable an application to switch modes by calling
Set this flag to enable an application to render using GDI on a swap chain or a surface. This will allow the application to call
Set this flag to indicate that the swap chain might contain protected content; therefore, the operating system supports the creation of the swap chain only when driver and hardware protection is used. If the driver and hardware do not support content protection, the call to create a resource for the swap chain fails.
Direct3D 11:??This enumeration value is supported starting with Windows Developer Preview.Set this flag to indicate that shared resources that are created within the swap chain must be protected by using the driver?s mechanism for restricting access to shared surfaces.
Direct3D 11:??This enumeration value is supported starting with Windows Developer Preview.Set this flag to restrict presented content to the local displays. Therefore, the presented content is not accessible via remote accessing or through the desktop duplication APIs.
This flag supports the window content protection features of Windows. Applications can use this flag to protect their own onscreen window content from being captured or copied through a specific set of public operating system features and APIs.
If you use this flag with windowed (
Options for handling pixels in a display surface after calling
This enumeration is used by the
This enumeration is also used by the
The primary difference between presentation models is how back-buffer contents get to the Desktop Window Manager (DWM) for composition. In the bitblt model, which is used with the
Regardless of whether the flip model is more efficient, an application still might choose the bitblt model for the following reasons:
The bitblt model is the only way to mix GDI and DirectX presentation.
In the flip model, the application must create the swap chain with
Creates a DXGI 1.1 factory that generates objects used to enumerate and specify video graphics settings.
-The globally unique identifier (
Address of a reference to an
Returns
Use a DXGI 1.1 factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the full-screen display mode.
If the CreateDXGIFactory1 function succeeds, the reference count on the
This entry point is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Note??Do not mix the use of DXGI 1.0 (
The
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
Gets a DXGI 1.1 description of an adapter (or video card).
-A reference to a
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
Gets a DXGI 1.1 description of an adapter (or video card).
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a Microsoft DirectX Graphics Infrastructure (DXGI) 1.2 description of an adapter or video card. This description includes information about the granularity at which the graphics processing unit (GPU) can be preempted from performing its current task.
-Use the GetDesc2 method to get a DXGI 1.2 description of an adapter. To get a DXGI 1.1 description, use the
The Windows Display Driver Model (WDDM) scheduler can preempt the GPU's execution of application tasks. The granularity at which the GPU can be preempted from performing its current task in the WDDM 1.1 or earlier driver model is a direct memory access (DMA) buffer for graphics tasks or a compute packet for compute tasks. The GPU can switch between tasks only after it completes the currently executing unit of work, a DMA buffer or a compute packet.
A DMA buffer is the largest independent unit of graphics work that the WDDM scheduler can submit to the GPU. This buffer contains a set of GPU instructions that the WDDM driver and GPU use. A compute packet is the largest independent unit of compute work that the WDDM scheduler can submit to the GPU. A compute packet contains dispatches (for example, calls to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a Microsoft DirectX Graphics Infrastructure (DXGI) 1.2 description of an adapter or video card. This description includes information about the granularity at which the graphics processing unit (GPU) can be preempted from performing its current task.
-A reference to a
Returns
Use the GetDesc2 method to get a DXGI 1.2 description of an adapter. To get a DXGI 1.1 description, use the
The Windows Display Driver Model (WDDM) scheduler can preempt the GPU's execution of application tasks. The granularity at which the GPU can be preempted from performing its current task in the WDDM 1.1 or earlier driver model is a direct memory access (DMA) buffer for graphics tasks or a compute packet for compute tasks. The GPU can switch between tasks only after it completes the currently executing unit of work, a DMA buffer or a compute packet.
A DMA buffer is the largest independent unit of graphics work that the WDDM scheduler can submit to the GPU. This buffer contains a set of GPU instructions that the WDDM driver and GPU use. A compute packet is the largest independent unit of compute work that the WDDM scheduler can submit to the GPU. A compute packet contains dispatches (for example, calls to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a Microsoft DirectX Graphics Infrastructure (DXGI) 1.2 description of an adapter or video card. This description includes information about the granularity at which the graphics processing unit (GPU) can be preempted from performing its current task.
-Use the GetDesc2 method to get a DXGI 1.2 description of an adapter. To get a DXGI 1.1 description, use the
The Windows Display Driver Model (WDDM) scheduler can preempt the GPU's execution of application tasks. The granularity at which the GPU can be preempted from performing its current task in the WDDM 1.1 or earlier driver model is a direct memory access (DMA) buffer for graphics tasks or a compute packet for compute tasks. The GPU can switch between tasks only after it completes the currently executing unit of work, a DMA buffer or a compute packet.
A DMA buffer is the largest independent unit of graphics work that the WDDM scheduler can submit to the GPU. This buffer contains a set of GPU instructions that the WDDM driver and GPU use. A compute packet is the largest independent unit of compute work that the WDDM scheduler can submit to the GPU. A compute packet contains dispatches (for example, calls to the
An
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
The
Sets the number of frames that the system is allowed to queue for rendering.
-The maximum number of back buffer frames that a driver can queue. The value defaults to 3, but can range from 1 to 16. A value of 0 will reset latency to the default. For multi-head devices, this value is specified per-head.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets the number of frames that the system is allowed to queue for rendering.
-This value is set to the number of frames that can be queued for render. This value defaults to 3, but can range from 1 to 16.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-Gets or sets the number of frames that the system is allowed to queue for rendering.
-This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Flushes any outstanding rendering commands and sets the specified event object to the signaled state after all previously submitted rendering commands complete.
-EnqueueSetEvent calls the SetEvent function on the event object after all previously submitted rendering commands complete or the device is removed.
After an application calls EnqueueSetEvent, it can immediately call the WaitForSingleObject function to put itself to sleep until rendering commands complete.
You cannot use EnqueueSetEvent to determine work completion that is associated with presentation (
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows the operating system to free the video memory of resources by discarding their content.
-The number of resources in the ppResources argument array.
An array of references to
A
OfferResources returns:
The priority value that the Priority parameter specifies describes how valuable the caller considers the content to be. The operating system uses the priority value to discard resources in order of priority. The operating system discards a resource that is offered with low priority before it discards a resource that is offered with a higher priority.
If you call OfferResources to offer a resource while the resource is bound to the pipeline, the resource is unbound. You cannot call OfferResources on a resource that is mapped. After you offer a resource, the resource cannot be mapped or bound to the pipeline until you call the IDXGIDevice2::ReclaimResource method to reclaim the resource. You cannot call OfferResources to offer immutable resources.
To offer shared resources, call OfferResources on only one of the sharing devices. To ensure exclusive access to the resources, you must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows the operating system to free the video memory of resources by discarding their content.
-The number of resources in the ppResources argument array.
An array of references to
A
OfferResources returns:
The priority value that the Priority parameter specifies describes how valuable the caller considers the content to be. The operating system uses the priority value to discard resources in order of priority. The operating system discards a resource that is offered with low priority before it discards a resource that is offered with a higher priority.
If you call OfferResources to offer a resource while the resource is bound to the pipeline, the resource is unbound. You cannot call OfferResources on a resource that is mapped. After you offer a resource, the resource cannot be mapped or bound to the pipeline until you call the IDXGIDevice2::ReclaimResource method to reclaim the resource. You cannot call OfferResources to offer immutable resources.
To offer shared resources, call OfferResources on only one of the sharing devices. To ensure exclusive access to the resources, you must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Restores access to resources that were previously offered by calling
ReclaimResources returns:
After you call
To reclaim shared resources, call ReclaimResources only on one of the sharing devices. To ensure exclusive access to the resources, you must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Restores access to resources that were previously offered by calling
ReclaimResources returns:
After you call
To reclaim shared resources, call ReclaimResources only on one of the sharing devices. To ensure exclusive access to the resources, you must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Flushes any outstanding rendering commands and sets the specified event object to the signaled state after all previously submitted rendering commands complete.
-A handle to the event object. The CreateEvent or OpenEvent function returns this handle. All types of event objects (manual-reset, auto-reset, and so on) are supported.
The handle must have the EVENT_MODIFY_STATE access right. For more information about access rights, see Synchronization Object Security and Access Rights.
Returns
EnqueueSetEvent calls the SetEvent function on the event object after all previously submitted rendering commands complete or the device is removed.
After an application calls EnqueueSetEvent, it can immediately call the WaitForSingleObject function to put itself to sleep until rendering commands complete.
You cannot use EnqueueSetEvent to determine work completion that is associated with presentation (
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a swap chain that is associated with an IWindow object for the output window for the swap chain.
-Note??Use this method in Metro style apps rather than
If you specify the width, height, or both (Width and Height members of
Because you can associate only one flip presentation model swap chain at a time with an IWindow, the Microsoft Direct3D?11 policy of deferring the destruction of objects can cause problems if you attempt to destroy a flip presentation model swap chain and replace it with another swap chain. For more info about this situation, see Deferred Destruction Issues with Flip Presentation Swap Chains.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Determines whether to use stereo mode.
-Indicates whether to use stereo mode. TRUE indicates that you can use stereo mode; otherwise,
We recommend that windowed applications call IsWindowedStereoEnabled before they attempt to use stereo. IsWindowedStereoEnabled returns TRUE if both of the following items are true:
The creation of a windowed stereo swap chain succeeds if the first requirement is met. However, if the adapter can't scan out stereo, the output on that adapter is reduced to mono.
The Direct3D 11.1 Simple Stereo 3D Sample shows how to add a stereoscopic 3D effect and how to respond to system stereo changes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a swap chain that is associated with an
Note??Do not use this method in Metro style apps. Instead, use
If you specify the width, height, or both (Width and Height members of
Because you can associate only one flip presentation model swap chain at a time with an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a swap chain that is associated with an IWindow object for the output window for the swap chain.
-A reference to the Direct3D device for the swap chain. This parameter cannot be
A reference to the IWindow object that is associated with the swap chain that CreateSwapChainForCoreWindow creates.
A reference to a
A reference to the
A reference to a variable that receives a reference to the
Note??Use this method in Metro style apps rather than
If you specify the width, height, or both (Width and Height members of
Because you can associate only one flip presentation model swap chain at a time with an IWindow, the Microsoft Direct3D?11 policy of deferring the destruction of objects can cause problems if you attempt to destroy a flip presentation model swap chain and replace it with another swap chain. For more info about this situation, see Deferred Destruction Issues with Flip Presentation Swap Chains.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Identifies the adapter on which a shared resource object was created.
-A handle to a shared resource object. The
A reference to a variable that receives a locally unique identifier (
GetSharedResourceAdapterLuid returns:
You cannot share resources across adapters. Therefore, you cannot open a shared resource on an adapter other than the adapter on which the resource was created. Call GetSharedResourceAdapterLuid before you open a shared resource to ensure that the resource was created on the appropriate adapter. To open a shared resource, call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Registers an application window to receive notification messages of changes of stereo status.
-The handle of the window to send a notification message to when stereo status change occurs.
Identifies the notification message to send.
A reference to a key value that an application can pass to the
RegisterStereoStatusWindow returns:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Registers to receive notification of changes in stereo status by using event signaling.
-A handle to the event object that the operating system sets when notification of stereo status change occurs. The CreateEvent or OpenEvent function returns this handle.
A reference to a key value that an application can pass to the
RegisterStereoStatusEvent returns:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unregisters a window or an event to stop it from receiving notification when stereo status changes.
-A key value for the window or event to unregister. The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Registers an application window to receive notification messages of changes of occlusion status.
-The handle of the window to send a notification message to when occlusion status change occurs.
Identifies the notification message to send.
A reference to a key value that an application can pass to the
RegisterOcclusionStatusWindow returns:
Apps choose the Windows message that Windows sends when occlusion status changes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Registers to receive notification of changes in occlusion status by using event signaling.
-A handle to the event object that the operating system sets when notification of occlusion status change occurs. The CreateEvent or OpenEvent function returns this handle.
A reference to a key value that an application can pass to the
RegisterOcclusionStatusEvent returns:
If you call RegisterOcclusionStatusEvent multiple times with the same event handle, RegisterOcclusionStatusEvent fails with
If you call RegisterOcclusionStatusEvent multiple times with the different event handles, RegisterOcclusionStatusEvent properly registers the events.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unregisters a window or an event to stop it from receiving notification when occlusion status changes.
-A key value for the window or event to unregister. The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a swap chain that you can use to send Direct3D content into the DirectComposition API or the Windows.UI.Xaml framework to compose in a window.
-You can use composition swap chains with either DirectComposition?s IDCompositionVisual interface or XAML?s SwapChainBackgroundPanel class. For DirectComposition, you can call the IDCompositionVisual::SetContent method to set the swap chain as the content of a visual object, which then allows you to bind the swap chain to the visual tree. For XAML, the SwapChainBackgroundPanel class exposes a classic COM interface
The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Determines whether to use stereo mode.
-We recommend that windowed applications call IsWindowedStereoEnabled before they attempt to use stereo. IsWindowedStereoEnabled returns TRUE if both of the following items are true:
The creation of a windowed stereo swap chain succeeds if the first requirement is met. However, if the adapter can't scan out stereo, the output on that adapter is reduced to mono.
The Direct3D 11.1 Simple Stereo 3D Sample shows how to add a stereoscopic 3D effect and how to respond to system stereo changes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Provides interoperation between XAML and a DirectX swap chain.
-This interface provides the native implementation of the Windows::UI::XAML::Control::SwapChainBackgroundPanel Windows Runtime type. To obtain a reference to
Microsoft::WRL::ComPtr<-> m_swapChainNative; - // ... - IInspectable* panelInspectable = (IInspectable*) reinterpret_cast<IInspectable*>(swapChainPanel); - panelInspectable->QueryInterface(__uuidof( ), (void **)&m_swapChainNative);
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets the DirectX swap chain for SwapChainBackgroundPanel.
-If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets the DirectX swap chain for SwapChainBackgroundPanel.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Provides an interface for the implementation of drawing behaviors when a VirtualSurfaceImageSource requests an update.
-This interface is implemented by the developer to provide specific drawing behaviors for updates to a VirtualSurfaceImageSource. Classes that implement this interface are provided to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Performs the drawing behaviors when an update to VirtualSurfaceImageSource is requested.
-If this method succeeds, it returns
This method is implemented by the developer.
-Using a key, acquires exclusive rendering access to a shared resource.
-The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX value of the D3D10_RESOURCE_MISC_FLAG enumeration, you must call the AcquireSync method before rendering to the surface. You must call the ReleaseSync method when you are done rendering to a surface.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, acquires exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method will succeed when the device that currently owns the surface calls the
The time-out interval, in milliseconds. This method will return if the interval elapses, and the keyed mutex has not been released using the specified Key. If this value is set to zero, the AcquireSync method will test to see if the keyed mutex has been released and returns immediately. If this value is set to INFINITE, the time-out interval will never elapse.
Return
If the owning device attempted to create another keyed mutex on the same shared resource, AcquireSync returns E_FAIL.
AcquireSync can also return the following DWORD constants. Therefore, you should explicitly check for these constants. If you only use the SUCCEEDED macro on the return value to determine if AcquireSync succeeded, you will not catch these constants.
The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX value of the D3D10_RESOURCE_MISC_FLAG enumeration, you must call the AcquireSync method before rendering to the surface. You must call the ReleaseSync method when you are done rendering to a surface.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, releases exclusive rendering access to a shared resource.
-A value that indicates which device to give access to. This method succeeds when the device that currently owns the surface calls the ReleaseSync method using the same value. This value can be any UINT64 value.
Returns
If the device attempted to release a keyed mutex that is not valid or owned by the device, ReleaseSync returns E_FAIL.
The ReleaseSync method releases a lock to a surface that is shared between multiple devices. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX value of the D3D10_RESOURCE_MISC_FLAG enumeration, you must call the
After you call the ReleaseSync method, the shared resource is unset from the rendering pipeline.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
An
You can create a swap chain in several ways. If your application uses Direct3D, create a swap chain when you create a device by
- calling D3D10CreateDeviceAndSwapChain or D3D11CreateDeviceAndSwapChain. If your application does not need Direct3D, create a swap chain for use directly with DXGI by
- calling
[Starting with Direct3D 11.1, we recommend not to use Present anymore to present a rendered image. Instead, use
Presents a rendered image to the user.
-Possible return values include:
Note??The Present method can return either
For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.
Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.
| Differences between Direct3D 9 and Direct3D 10: Specifying |
?
For flip presentation model swap chains that you create with the
Suppose the following frames with sync-interval values are queued from oldest (A) to newest (E) before you call Present.
A: 3, B: 0, C: 0, D: 1, E: 0
When you call Present, the runtime shows frame A for 3 vertical blank intervals, then frame D for 1 vertical blank interval, and then frame E until you submit a new presentation. The runtime discards frames C and D.
-Accesses one of the swap-chain's back buffers.
-A zero-based buffer index.
If the swap chain's swap effect is
If the swap chain's swap effect is either
The type of interface used to manipulate the buffer. See remarks.
A reference to a back-buffer interface.
Returns one of the following DXGI_ERROR.
Sets the display state to windowed or full screen.
-A Boolean value that specifies whether to set the display state to windowed or full screen. TRUE for full screen, and
If you pass TRUE to the Fullscreen parameter to set the display state to full screen, you can optionally set this parameter to a reference to an
This methods returns:
When this error is returned, an application can continue to run in windowed mode and try to switch to full-screen mode later.
DXGI may change the display state of a swap chain in response to end user or system requests.
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through SetFullscreenState; that is, do not set the Windowed member of
If a Metro style app calls SetFullscreenState to set the display state to full screen, SetFullscreenState fails with
You cannot call SetFullscreenState on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
For the flip presentation model, after you transition the display state to full screen, you must call ResizeBuffers to ensure that your call to
Get the state associated with full-screen mode.
-A reference to a boolean whose value is either:
A reference to the output target (see
Returns one of the following DXGI_ERROR.
When the swap chain is in full-screen mode, a reference to the target output will be returned and its reference count will be incremented.
-[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use
Get a description of the swap chain.
-Returns one of the following DXGI_ERROR.
Changes the swap chain's back buffer size, format, and number of buffers. This should be called when the application window is resized.
-The number of buffers in the swap chain (including all back and front buffers). This number can be different from the number of buffers with which you created the swap chain. This number can't be greater than DXGI_MAX_SWAP_CHAIN_BUFFERS. Set this number to zero to preserve the existing number of buffers in the swap chain. You can't specify greater than two buffers for the flip presentation model.
New width of the back buffer. If you specify zero, DXGI will use the width of the client area of the target window. You can't specify the width as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
New height of the back buffer. If you specify zero, DXGI will use the height of the client area of the target window. You can't specify the height as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
A
A combination of
Returns
You can't resize a swap chain unless you release all outstanding references to its back buffers. You must release all of its direct and indirect references on the back buffers in order for ResizeBuffers to succeed.
Direct references are held by the application after it calls AddRef on a resource.
Indirect references are held by views to a resource, binding a view of the resource to a device context, a command list that used the resource, a command list that used a view to that resource, a command list that executed another command list that used the resource, and so on.
Before you call ResizeBuffers, ensure that the application releases all references (by calling the appropriate number of Release invocations) on the resources, any views to the resource, and any command lists that use either the resources or views, and ensure that neither the resource nor a view is still bound to a device context. You can use
For swap chains that you created with
We recommend that you call ResizeBuffers when a client window is resized (that is, when an application receives a WM_SIZE message).
The only difference between ResizeBuffers in Windows Developer Preview and ResizeBuffers in Windows?7 is with flip presentation model swap chains that you create with the
Resizes the output target.
-A reference to a
Returns a code that indicates success or failure.
ResizeTarget resizes the target window when the swap chain is in windowed mode, and changes the display mode on the target output when the swap chain is in full-screen mode. Therefore, applications can call ResizeTarget to resize the target window (rather than a Microsoft Win32API such as SetWindowPos) without knowledge of the swap chain display mode.
If a Metro style app calls ResizeTarget, it fails with
You cannot call ResizeTarget on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-A reference to the output interface (see
Returns one of the following DXGI_ERROR.
If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-A reference to a
Returns one of the DXGI_ERROR values.
You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the
Gets the number of times that
Returns one of the DXGI_ERROR values.
For info about presentation statistics for a frame, see
[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use
Get a description of the swap chain.
-Get the output (the display monitor) that contains the majority of the client area of the target window.
-If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
-Gets performance statistics about the last render frame.
-You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the
Gets the number of times that
For info about presentation statistics for a frame, see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Provides presentation capabilities that are enhanced from
You can create a swap chain by
- calling
Note??Some stereo features like the advanced presentation flags are not represented by an explicit interface change. Furthermore, the original (
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a description of the swap chain.
-A reference to a
Returns
[This documentation is preliminary and is subject to change.]
Gets a description of a full-screen swap chain.
-A reference to a
GetFullscreenDesc returns:
The semantics of GetFullscreenDesc are identical to that of the IDXGISwapchain::GetDesc method for
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Retrieves the underlying
Returns
If pHwnd receives
Applications call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Retrieves the underlying IWindow object for this swap-chain object.
-A reference to the globally unique identifier (
A reference to a variable that receives a reference to the IWindow object.
GetCoreWindow returns:
Applications call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Presents a frame on the display screen.
-An integer that specifies how to synchronize presentation of a frame with the vertical blank.
For the bit-block transfer (bitblt) model, values are:
For the flip model, values are:
For an example that shows how sync-interval values affect a flip presentation queue, see Remarks.
If the update region straddles more than one output (each represented by
An integer value that contains swap-chain presentation options. These options are defined by the DXGI_PRESENT constants.
A reference to a
Possible return values include:
An application can use Present1 to optimize presentation by specifying scroll and dirty rectangles. When the runtime has information about these rectangles, the runtime can then perform necessary bitblts during presentation more efficiently and pass this metadata to the Desktop Window Manager (DWM). The DWM can then use the metadata to optimize presentation and pass the metadata to indirect displays and terminal servers to optimize traffic over the wire. An application must confine its modifications to only the dirty regions that it passes to Present1, as well as modify the entire dirty region to avoid undefined resource contents from being exposed.
For flip presentation model swap chains that you create with the
Suppose the following frames with sync-interval values are queued from oldest (A) to newest (E) before you call Present1.
A: 3, B: 0, C: 0, D: 1, E: 0
When you call Present1, the runtime shows frame A for 3 vertical blank intervals, then frame D for 1 vertical blank interval, and then frame E until you submit a new presentation. The runtime discards frames B and C.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Determines whether a swap chain supports ?temporary mono.?
-Indicates whether to use the swap chain in temporary mono mode. TRUE indicates that you can use temporary-mono mode; otherwise,
Temporary mono is a feature where a stereo swap chain can be presented using only the content in the left buffer. To present using the left buffer as a mono buffer, an application calls the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the output (the display monitor) to which you can restrict the contents of a present operation.
- A reference to a buffer that receives a reference to the
Returns
If the method succeeds, the runtime fills the buffer at ppRestrictToOutput with a reference to the restrict-to output interface. This restrict-to output interface has its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Changes the background color of the swap chain.
-A reference to a DXGI_RGBA structure that specifies the background color to set.
SetBackgroundColor returns:
The background color affects only swap chains that you create with
When you set the background color, it is not immediately realized. It takes effect in conjunction with your next call to the
When you call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Retrieves the background color of the swap chain.
-A reference to a DXGI_RGBA structure that receives the background color of the swap chain.
GetBackgroundColor returns:
Note??The background color that GetBackgroundColor retrieves does not indicate what the screen currently displays. The background color indicates what the screen will display with your next call to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the rotation of the back buffers for the swap chain.
-A
SetRotation returns:
You can only use SetRotation to rotate the back buffers for flip-model swap chains that you present in windowed mode.
SetRotation isn't supported for rotating the back buffers for flip-model swap chains that you present in full-screen mode. In this situation, SetRotation doesn't fail, but you must ensure that you specify no rotation (
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rotation of the back buffers for the swap chain.
-A reference to a variable that receives a
Returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a description of the swap chain.
-[This documentation is preliminary and is subject to change.]
Gets a description of a full-screen swap chain.
-The semantics of GetFullscreenDesc are identical to that of the IDXGISwapchain::GetDesc method for
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Retrieves the underlying
Applications call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Determines whether a swap chain supports ?temporary mono.?
-Temporary mono is a feature where a stereo swap chain can be presented using only the content in the left buffer. To present using the left buffer as a mono buffer, an application calls the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the output (the display monitor) to which you can restrict the contents of a present operation.
-If the method succeeds, the runtime fills the buffer at ppRestrictToOutput with a reference to the restrict-to output interface. This restrict-to output interface has its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Retrieves the background color of the swap chain.
-Note??The background color that GetBackgroundColor retrieves does not indicate what the screen currently displays. The background color indicates what the screen will display with your next call to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rotation of the back buffers for the swap chain.
-Describes an adapter (or video card) by using DXGI 1.0.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
Describes an adapter (or video card) using DXGI 1.1.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
A value of the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes an adapter (or video card) that uses Microsoft DirectX Graphics Infrastructure (DXGI) 1.2.
-The
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
A value of the
A value of the
A value of the
Describes timing and presentation statistics for a frame.
-You initialize the
You can only use
The values in the PresentCount and PresentRefreshCount members indicate information about when a frame was presented on the display screen. You can use these values to determine whether a glitch occurred. The values in the SyncRefreshCount and SyncQPCTime members indicate timing information that you can use for audio and video synchronization or very precise animation. If the swap chain draws in full-screen mode, these values are based on when the computer booted. - If the swap chain draws in windowed mode, these values are based on when the swap chain is created.
-A value that represents the running total count of times that an image was presented to the monitor since the computer booted.
Note??The number of times that an image was presented to the monitor is not necessarily the same as the number of times that you called
A value that represents the running total count of v-blanks at which the last image was presented to the monitor and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the running total count of v-blanks when the scheduler last sampled the machine time by calling QueryPerformanceCounter and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the high-resolution performance counter timer. This value is the same as the value returned by the QueryPerformanceCounter function.
Reserved. Always returns 0.
Controls the settings of a gamma curve.
-The
A
A
An array of
Controls the gamma capabilities of an adapter.
-To get a list of the capabilities for controlling gamma correction, call
True if scaling and offset operations are supported during gamma correction; otherwise, false.
A value describing the maximum range of the control-point positions.
A value describing the minimum range of the control-point positions.
A value describing the number of control points in the array.
An array of values describing control points; the maximum length of control points is 1025.
Describes a mapped rectangle that is used to access a surface.
-The
A value that describes the width, in bytes, of the surface.
A reference to the image buffer of the surface.
Describes a display mode.
-The following format values are valid for display modes and when you create a bit-block transfer (bitblt) model swap chain. The valid values depend on the feature level that you are working with.
Feature level >= 9.1
Feature level >= 10.0
Feature level >= 11.0
You can pass one of these format values to
Starting with Windows Developer Preview for a flip model swap chain (that is, a swap chain that has the
Because of the relaxed render target creation rules that Direct3D 11 has for back buffers, applications can create a
A value that describes the resolution width. If you specify the width as zero when you call the
A value describing the resolution height. If you specify the height as zero when you call the
A
A
A member of the
A member of the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes a display mode and whether the display mode supports stereo.
-A value that describes the resolution width.
A value that describes the resolution height.
A
A
A
A
Specifies whether the full-screen display mode is stereo. TRUE if stereo; otherwise,
Describes an output or physical connection between the adapter (video card) and a device.
-The
A string that contains the name of the output device.
A
True if the output is attached to the desktop; otherwise, false.
A member of the
An
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes information about present that helps the operating system optimize presentation.
-The scroll rectangle and the list of dirty rectangles could overlap. In this situation, the dirty rectangles take priority. Applications can then have pieces of dynamic content on top of a scrolled area. For example, an application could scroll a page and play video at the same time.
The following diagram and coordinates illustrate this example.
DirtyRectsCount = 2
- pDirtyRects[ 0 ] = { 10, 30, 40, 50 } // Video
- pDirtyRects[ 1 ] = { 0, 70, 50, 80 } // New line
- *pScrollRect = { 0, 0, 50, 70 }
- *pScrollOffset = { 0, -10 }
- Parts of the previous frame and content that the application renders are combined to produce the final frame that the operating system presents on the display screen. Most of the window is scrolled from the previous frame. The application must update the video frame with the new chunk of content that appears due to scrolling.
The dashed rectangle shows the scroll rectangle in the current frame. The scroll rectangle is specified by the pScrollRect member. - The arrow shows the scroll offset. The scroll offset is specified by the pScrollOffset member. - Filled rectangles show dirty rectangles that the application updated with new content. The filled rectangles are specified by the DirtyRectsCount and pDirtyRects members.
The scroll rectangle and offset are not supported for the
The actual implementation of composition and necessary bitblts is different for the bitblt model and the flip model.
-The number of updated rectangles that you update in the back buffer for the presented frame. The operating system uses this information to optimize presentation. You can set this member to 0 to indicate that you update the whole frame.
A list of updated rectangles that you update in the back buffer for the presented frame. An application must update every single pixel in each rectangle that it reports to the runtime; the application cannot assume that the pixels are saved from the previous frame. For more information about updating dirty rectangles, see Remarks. You can set this member to
A reference to the scrolled rectangle. The scrolled rectangle is the rectangle of the previous frame from which the runtime bit-block transfers (bitblts) content. The runtime also uses the scrolled rectangle to optimize presentation in terminal server and indirect display scenarios.
The scrolled rectangle also describes the destination rectangle, that is, the region on the current frame that is filled with scrolled content. You can set this member to
A reference to the offset of the scrolled area that goes from the source rectangle (of previous frame) to the destination rectangle (of current frame). You can set this member to
Represents a rational number.
-The
An unsigned integer value representing the top of the rational number.
An unsigned integer value representing the bottom of the rational number.
Describes multi-sampling parameters for a resource.
-The default sampler mode, with no anti-aliasing, has a count of 1 and a quality level of 0.
If multi-sample antialiasing is being used, all bound render targets and depth buffers must have the same sample counts and quality levels.
| Differences between Direct3D 10.0 and Direct3D 10.1 and between Direct3D 10.0 and Direct3D 11: Direct3D 10.1 has defined two standard quality levels: D3D10_STANDARD_MULTISAMPLE_PATTERN and D3D10_CENTER_MULTISAMPLE_PATTERN in the D3D10_STANDARD_MULTISAMPLE_QUALITY_LEVELS enumeration in D3D10_1.h. Direct3D 11 has defined two standard quality levels: |
?
-The number of multisamples per pixel.
The image quality level. The higher the quality, the lower the performance. The valid range is between zero and one less than the level returned by ID3D10Device::CheckMultisampleQualityLevels for Direct3D 10 or
For Direct3D 10.1 and Direct3D 11, you can use two special quality level values. For more information about these quality level values, see Remarks.
Represents a handle to a shared resource.
-To create a shared surface, pass a shared-resource handle into the
A handle to a shared resource.
Describes a surface.
-A value describing the surface width.
A value describing the surface height.
A member of the
A member of the
Describes a swap chain.
-In full-screen mode, there is a dedicated front buffer; in windowed mode, the desktop is the front buffer.
If you create a swap chain with one buffer, specifying
For performance information about flipping swap-chain buffers in full-screen application, see Full-Screen Application Performance Hints.
-A
A
A member of the DXGI_USAGE enumerated type that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
A value that describes the number of buffers in the swap chain. When you call
An
A Boolean value that specifies whether the output is in windowed mode. TRUE if the output is in windowed mode; otherwise,
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through
For more information about choosing windowed verses full screen, see
A member of the
A member of the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes a swap chain.
-Note??You cannot cast a
In full-screen mode, there is a dedicated front buffer; in windowed mode, the desktop is the front buffer.
For a flip-model swap chain (that is, a swap chain that has the
A value that describes the resolution width. If you specify the width as zero when you call the
A value that describes the resolution height. If you specify the height as zero when you call the
A
Specifies whether the full-screen display mode or the swap-chain back buffer is stereo. TRUE if stereo; otherwise,
A
A DXGI_USAGE-typed value that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
A value that describes the number of buffers in the swap chain. When you create a full-screen swap chain, you typically include the front buffer in this value.
A
A
A
A combination of
[This documentation is preliminary and is subject to change.]
Describes full-screen mode for a swap chain.
-A
A member of the
A member of the
Contains the content bounds, mask information, opacity settings, and other options for a layer resource.
-The content bounds of the layer. Content outside these bounds is not guaranteed to render.
The geometric mask specifies the area of the layer that is composited into the render target.
A value that specifies the antialiasing mode for the geometricMask.
A value that specifies the transform that is applied to the geometric mask when composing the layer.
An opacity value that is applied uniformly to all resources in the layer when compositing to the target.
A brush that is used to modify the opacity of the layer. The brush - is mapped to the layer, and the alpha channel of each mapped brush pixel is multiplied against the corresponding layer pixel.
A value that specifies whether the layer intends to render text with ClearType antialiasing.
Specifies the identifiers of the metadata items in an 8BIM IPTC digest metadata block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_BLOB] The embedded IPTC digest value.
Specifies the identifiers of the metadata items in an 8BIM IPTC block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UNKNOWN] The IPTC block embedded in this 8BIM IPTC block.
Specifies the identifiers of the metadata items in an 8BIMResolutionInfo block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UI4] The horizontal resolution of the image.
[VT_UI2] The units that the horizontal resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image width is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
[VT_UI4] The vertical resolution of the image.
[VT_UI2] The units that the vertical resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image height is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
Specifies the desired alpha channel usage.
-Use alpha channel.
Use a pre-multiplied alpha channel.
Ignore alpha channel.
Specifies the desired cache usage.
-The CreateBitmap of the
Do not cache the bitmap.
Cache the bitmap when needed.
Cache the bitmap at initialization.
Specifies the capabilities of the decoder.
-Decoder recognizes the image was encoded with an encoder produced by the same vendor.
Decoder can decode all the images within an image container.
Decoder can decode some of the images within an image container.
Decoder can enumerate the metadata blocks within a container format.
Decoder can find and decode a thumbnail.
Specifies the type of dither algorithm to apply when converting between image formats.
-A solid color algorithm without dither.
A solid color algorithm without dither.
A 4x4 ordered dither algorithm.
An 8x8 ordered dither algorithm.
A 16x16 ordered dither algorithm.
A 4x4 spiral dither algorithm.
An 8x8 spiral dither algorithm.
A 4x4 dual spiral dither algorithm.
An 8x8 dual spiral dither algorithm.
An error diffusion algorithm.
Specifies the cache options available for an encoder.
-The encoder is cached in memory. This option is not supported.
The encoder is cached to a temporary file. This option is not supported.
The encoder is not cached.
Specifies the sampling or filtering mode to use when scaling an image.
-A nearest neighbor interpolation algorithm. Also known as nearest pixel or point interpolation.
The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.
A bilinear interpolation algorithm.
The output pixel values are computed as a weighted average of the nearest four pixels in a 2x2 grid.
A bicubic interpolation algorithm.
Destination pixel values are computed as a weighted average of the nearest sixteen pixels in a 4x4 grid.
A Fant resampling algorithm.
Destination pixel values are computed as a weighted average of the all the pixels that map to the new pixel.
Specifies access to an
Specifies the type of palette used for an indexed image format.
-An arbitrary custom palette provided by caller.
An optimal palette generated using a median-cut algorithm. Derived from the colors in an image.
A black and white palette.
A palette that has its 8-color on-off primaries and the 16 system colors added. With duplicates removed, 16 colors are available.
A palette that has 3 intensity levels of each primary: 27-color on-off primaries and the 16 system colors added. With duplicates removed, 35 colors are available.
A palette that has 4 intensity levels of each primary: 64-color on-off primaries and the 16 system colors added. With duplicates removed, 72 colors are available.
A palette that has 5 intensity levels of each primary: 125-color on-off primaries and the 16 system colors added. With duplicates removed, 133 colors are available.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as WICBitmapPaletteFixedHalftoneWeb.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as
A palette that has its 252-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has its 256-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has 4 shades of gray.
A palette that has 16 shades of gray.
A palette that has 256 shades of gray.
Specifies the flip and rotation transforms.
-A rotation of 0 degrees.
A clockwise rotation of 90 degrees.
A clockwise rotation of 180 degrees.
A clockwise rotation of 270 degrees.
A horizontal flip. Pixels are flipped around the vertical y-axis.
A vertical flip. Pixels are flipped around the horizontal x-axis.
Specifies the color context types.
-An uninitialized color context.
A color context profile.
An EXIF color space color context.
Specifies component enumeration options.
-Enumerate signed components.
Force a read of the registry when enumerating components.
Enumerate disabled components.
Enumerate unsigned components.
Enumerate only built in components.
Specifies the component signing status.
-A signed component.
An unsigned component
A component is safe.
Components that do not have a binary component to sign, such as a pixel format, should return this value.
A component has been disabled.
Specifies the type of Windows Imaging Component (WIC) component.
-A WIC decoder.
A WIC encoder.
A WIC pixel converter.
A WIC metadata reader.
A WIC metadata writer.
A WIC pixel format.
All WIC components.
Specifies decode options.
-Cache metadata when needed.
Cache metadata when decoder is loaded.
Specifies the application extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_UI1 | VT_VECTOR] Indicates a string that identifies the application.
[VT_UI1 | VT_VECTOR] Indicates data that is exposed by the application.
Specifies the comment extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_LPSTR] Indicates the comment text.
Specifies the graphic control extension metadata properties that define the transitions between each frame animation for Graphics Interchange Format (GIF) images.
-[VT_UI1] Indicates the disposal requirements. 0 - no disposal, 1 - do not dispose, 2 - restore to background color, 3 - restore to previous.
[VT_BOOL] Indicates the user input flag. TRUE if user input should advance to the next frame; otherwise,
[VT_BOOL] Indicates the transparency flag. TRUE if a transparent color in is in the color table for this frame; otherwise,
[VT_UI2] Indicates how long to display the next frame before advancing to the next frame, in units of 1/100th of a second.
[VT_UI1] Indicates which color in the palette should be treated as transparent.
Specifies the image descriptor metadata properties for Graphics Interchange Format (GIF) frames.
-[VT_UI2] Indicates the X offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates the Y offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates width of this frame, in pixels.
[VT_UI2] Indicates height of this frame, in pixels.
[VT_BOOL] Indicates the local color table flag. TRUE if global color table is present; otherwise,
[VT_BOOL] Indicates the interlace flag. TRUE if image is interlaced; otherwise,
[VT_BOOL] Indicates the sorted color table flag. TRUE if the color table is sorted from most frequently to least frequently used color; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
Specifies the logical screen descriptor properties for Graphics Interchange Format (GIF) metadata.
-[VT_UI1 | VT_VECTOR] Indicates the signature property.
[VT_UI2] Indicates the width in pixels.
[VT_UI2] Indicates the height in pixels.
[VT_BOOL] Indicates the global color table flag. TRUE if a global color table is present; otherwise,
[VT_UI1] Indicates the color resolution in bits per pixel.
[VT_BOOL] Indicates the sorted color table flag. TRUE if the table is sorted; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
[VT_UI1] Indicates the index within the color table to use for the background (pixels not defined in the image).
[VT_UI1] Indicates the factor used to compute an approximation of the aspect ratio.
Specifies the JPEG chrominance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a chrominance table.
Specifies the JPEG comment properties.
-Indicates the metadata property is comment text.
Specifies the JPEG luminance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a luminance table.
Specifies the JPEG YCrCB subsampling options.
-The native JPEG encoder uses
The default subsampling option.
Subsampling option that uses both horizontal and vertical decimation.
Subsampling option that uses horizontal decimation .
Subsampling option that uses no decimation.
Specifies named white balances for raw images.
-The default white balance.
A daylight white balance.
A cloudy white balance.
A shade white balance.
A tungsten white balance.
A fluorescent white balance.
Daylight white balance.
A flash white balance.
A custom white balance. This is typically used when using a picture (grey-card) as white balance.
An automatic balance.
An "as shot" white balance.
Specifies the Portable Network Graphics (PNG) background (bKGD) chunk metadata properties.
-Indicates the background color. There are three possible types, depending on the image's pixel format.
Specifies the index of the background color in an image with an indexed pixel format.
Specifies the background color in a grayscale image.
Specifies the background color in an RGB image as three USHORT values: {0xRRRR, 0xGGGG, 0xBBBB}.
Specifies the Portable Network Graphics (PNG) cHRM chunk metadata properties for CIE XYZ chromaticity.
-[VT_UI4] Indicates the whitepoint x value ratio.
[VT_UI4] Indicates the whitepoint y value ratio.
[VT_UI4] Indicates the red x value ratio.
[VT_UI4] Indicates the red y value ratio.
[VT_UI4] Indicates the green x value ratio.
[VT_UI4] Indicates the green y value ratio.
[VT_UI4] Indicates the blue x value ratio.
[VT_UI4] Indicates the blue y value ratio.
Specifies the Portable Network Graphics (PNG) filters available for compression optimization.
-Indicates an unspecified PNG filter. This enables WIC to algorithmically choose the best filtering option for the image.
Indicates no PNG filter.
Indicates a PNG sub filter.
Indicates a PNG up filter.
Indicates a PNG average filter.
Indicates a PNG paeth filter.
Indicates a PNG adaptive filter. This enables WIC to choose the best filtering mode on a per-scanline basis.
Specifies the Portable Network Graphics (PNG) gAMA chunk metadata properties.
-[VT_UI4] Indicates the gamma value.
Specifies the Portable Network Graphics (PNG) hIST chunk metadata properties.
-[VT_VECTOR | VT_UI2] Indicates the approximate usage frequency of each color in the color palette.
Specifies the Portable Network Graphics (PNG) iCCP chunk metadata properties.
-[VT_LPSTR] Indicates the International Color Consortium (ICC) profile name.
[VT_VECTOR | VT_UI1] Indicates the embedded ICC profile.
Specifies the Portable Network Graphics (PNG) iTXT chunk metadata properties.
-[VT_LPSTR] Indicates the keywords in the iTXT metadata chunk.
[VT_UI1] Indicates whether the text in the iTXT chunk is compressed. 1 if the text is compressed; otherwise, 0.
[VT_LPSTR] Indicates the human language used by the translated keyword and the text.
[VT_LPWSTR] Indicates a translation of the keyword into the language indicated by the language tag.
[VT_LPWSTR] Indicates additional text in the iTXT metadata chunk.
Specifies the Portable Network Graphics (PNG) sRGB chunk metadata properties.
-[VT_UI1] Indicates the rendering intent for an sRGB color space image. The rendering intents have the following meaning.
| Value | Meaning |
|---|---|
| 0 | Perceptual |
| 1 | Relative colorimetric |
| 2 | Saturation |
| 3 | Absolute colorimetric |
?
Specifies the Portable Network Graphics (PNG) tIME chunk metadata properties.
-[VT_UI2] Indicates the year of the last modification.
[VT_UI1] Indicates the month of the last modification.
[VT_UI1] Indicates day of the last modification.
[VT_UI1] Indicates the hour of the last modification.
[VT_UI1] Indicates the minute of the last modification.
[VT_UI1] Indicates the second of the last modification.
Specifies when the progress notification callback should be called.
-The callback should be called when codec operations begin.
The callback should be called when codec operations end.
The callback should be called frequently to report status.
The callback should be called on all available progress notifications.
Specifies the progress operations to receive notifications for.
-Receive copy pixel operation.
Receive write pixel operation.
Receive all progress operations available.
Specifies the capability support of a raw image.
-The capability is not supported.
The capability supports only get operations.
The capability supports get and set operations.
Specifies the parameter set used by a raw codec.
-An as shot parameter set.
A user adjusted parameter set.
A codec adjusted parameter set.
Specifies the render intent of the next CopyPixels call.
-Specifies the rotation capabilities of the codec.
-Rotation is not supported.
Set operations for rotation is not supported.
90 degree rotations are supported.
All rotation angles are supported.
Specifies the access level of a Windows Graphics Device Interface (GDI) section.
-Indicates a read only access level.
Indicates a read/write access level.
Specifies the Tagged Image File Format (TIFF) compression options.
-Indicates a suitable compression algorithm based on the image and pixel format.
Indicates no compression.
Indicates a CCITT3 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a CCITT4 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a LZW compression algorithm.
Indicates a RLE compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a ZIP compression algorithm.
Indicates an LZWH differencing algorithm.
Defines methods that add the concept of writeability and static in-memory representations of bitmaps to
Because of to the internal memory representation implied by the
Exposes methods that refers to a source from which pixels are retrieved, but cannot be written back to.
-This interface provides a common way of accessing and linking together bitmaps, decoders, format converters, and scalers. Components that implement this interface can be connected together in a graph to pull imaging data through.
This interface defines only the notion of readability or being able to produce pixels. Modifying or writing to a bitmap is considered to be a specialization specific to bitmaps which have storage and is defined in the descendant interface
Retrieves the pixel width and height of the bitmap.
-A reference that receives the pixel width of the bitmap.
A reference that receives the pixel height of the bitmap
If this method succeeds, it returns
Retrieves the pixel format of the bitmap source..
-Receives the pixel format
If this method succeeds, it returns
The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the sampling rate between pixels and physical world measurements.
-A reference that receives the x-axis dpi resolution.
A reference that receives the y-axis dpi resolution.
If this method succeeds, it returns
Some formats, such as GIF and ICO, do not have full DPI support. For GIF, this method calculates the DPI values from the aspect ratio, using a base DPI of (96.0, 96.0). The ICO format does not support DPI at all, and the method always returns (96.0,96.0) for ICO images.
Additionally, WIC itself does not transform images based on the DPI values in an image. It is up to the caller to transform an image based on the resolution returned.
-Retrieves the color table for indexed pixel formats.
-An
Returns one of the following values.
| Return code | Description |
|---|---|
| | The palette was unavailable. |
| | The palette was successfully copied. |
?
If the
Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
The size of the buffer.
A reference to the buffer.
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Retrieves the pixel format of the bitmap source..
-The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the pixel width and height of the bitmap.
-Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-The palette to use for conversion.
If this method succeeds, it returns
Changes the physical resolution of the image.
-The horizontal resolution.
The vertical resolution.
If this method succeeds, it returns
This method has no effect on the actual pixels or samples stored in the bitmap. Instead the interpretation of the sampling rate is modified. This means that a 96 DPI image which is 96 pixels wide is one inch. If the physical resolution is modified to 48 DPI, then the bitmap is considered to be 2 inches wide but has the same number of pixels. If the resolution is less than REAL_EPSILON (1.192092896e-07F) the error code
Provides access to a rectangular area of the bitmap.
-The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-Exposes methods that produce a clipped version of the input bitmap for a specified rectangular region of interest.
-Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Exposes methods that provide information about a particular codec.
-Exposes methods that provide component information.
-Retrieves the component's
If this method succeeds, it returns
Retrieves the component's class identifier (CLSID)
-A reference that receives the component's CLSID.
If this method succeeds, it returns
Retrieves the signing status of the component.
-A reference that receives the
If this method succeeds, it returns
Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the name of component's author.
-The size of the wzAuthor buffer.
A reference that receives the name of the component's author. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's authors name. The author name is optional; if an author name is not specified by the component, the length returned is 0.
If this method succeeds, it returns
If cchAuthor is 0 and wzAuthor is
Retrieves the vendor
A reference that receives the component's vendor
If this method succeeds, it returns
Retrieves the component's version.
-The size of the wzVersion buffer.
A reference that receives a culture invariant string of the component's version.
A reference that receives the actual length of the component's version. The version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's specification version.
-The size of the wzSpecVersion buffer.
When this method returns, contain a culture invarient string of the component's specification version. The version form is NN.NN.NN.NN.
A reference that receives the actual length of the component's specification version. The specification version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a spec version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's friendly name, which is a human-readable display name for the component.
-The size of the wzFriendlyName buffer.
A reference that receives the friendly name of the component. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's friendly name.
If this method succeeds, it returns
If cchFriendlyName is 0 and wzFriendlyName is
Retrieves the component's
Retrieves the component's class identifier (CLSID)
-Retrieves the signing status of the component.
-Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the vendor
Retrieves the container
Receives the container
If this method succeeds, it returns
Retrieves the pixel formats the codec supports.
-The size of the pguidPixelFormats array. Use 0 on first call to determine the needed array size.
Receives the supported pixel formats. Use
The array size needed to retrieve all supported pixel formats.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the array size needed to retrieve all the supported pixel formats by calling it with cFormats set to 0 and pguidPixelFormats set to
Retrieves the color manangement version number the codec supports.
-The size of the version buffer. Use 0 on first call to determine needed buffer size.
Receives the color management version number. Use
The actual buffer size needed to retrieve the full color management version number.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchColorManagementVersion set to 0 and wzColorManagementVersion set to
Retrieves the name of the device manufacture associated with the codec.
-The size of the device manufacture's name. Use 0 on first call to determine needed buffer size.
Receives the device manufacture's name. Use
The actual buffer size needed to retrieve the device manufacture's name.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceManufacturer set to 0 and wzDeviceManufacturer set to
Retrieves a comma delimited list of device models associated with the codec.
-The size of the device models buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of device model names associated with the codec. Use
The actual buffer size needed to retrieve all of the device model names.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceModels set to 0 and wzDeviceModels set to
Retrieves a comma delimited sequence of mime types associated with the codec.
-The size of the mime types buffer. Use 0 on first call to determine needed buffer size.
Receives the mime types associated with the codec. Use
The actual buffer size needed to retrieve all mime types associated with the codec.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchMimeTypes set to 0 and wzMimeTypes set to
Retrieves a comma delimited list of the file name extensions associated with the codec.
-The size of the file name extension buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of file name extensions associated with the codec. Use
The actual buffer size needed to retrieve all file name extensions associated with the codec.
If this method succeeds, it returns
The default extension for an image encoder is the first item in the list of returned extensions.
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchFileExtensions set to 0 and wzFileExtensions set to
Retrieves a value indicating whether the codec supports animation.
-Receives TRUE if the codec supports images with timing information; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports chromakeys.
-Receives TRUE if the codec supports chromakeys; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports lossless formats.
-Receives TRUE if the codec supports lossless formats; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports multi frame images.
-Receives TRUE if the codec supports multi frame images; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the given mime type matches the mime type of the codec.
-The mime type to compare.
Receives TRUE if the mime types match; otherwise,
Retrieves the container
Retrieves a value indicating whether the codec supports animation.
-Retrieves a value indicating whether the codec supports chromakeys.
-Retrieves a value indicating whether the codec supports lossless formats.
-Retrieves a value indicating whether the codec supports multi frame images.
-Registers a progress notification callback function.
-A function reference to the application defined progress notification callback function. See ProgressNotificationCallback for the callback signature.
A reference to component data for the callback method.
The
If this method succeeds, it returns
Applications can only register a single callback. Subsequent registration calls will replace the previously registered callback. To unregister a callback, pass in
Progress is reported in an increasing order between 0.0 and 1.0. If dwProgressFlags includes
Exposes methods that represent a decoder.
The interface provides access to the decoder's properties such as global thumbnails (if supported), frames, and palette.
-There are a number of concrete implemenations of this interface representing each of the standard decoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), icon (ICO), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native decoder.
| CLSID Name | CLSID |
|---|---|
| 0x6b462062, 0x7cbf, 0x400d, 0x9f, 0xdb, 0x81, 0x3d, 0xd1, 0xf, 0x27, 0x78 | |
| 0x389ea17b, 0x5078, 0x4cde, 0xb6, 0xef, 0x25, 0xc1, 0x51, 0x75, 0xc7, 0x51 | |
| 0xc61bfcdf, 0x2e0f, 0x4aad, 0xa8, 0xd7, 0xe0, 0x6b, 0xaf, 0xeb, 0xcd, 0xfe | |
| 0x9456a480, 0xe88b, 0x43ea, 0x9e, 0x73, 0xb, 0x2d, 0x9b, 0x71, 0xb1, 0xca | |
| 0x381dda3c, 0x9ce9, 0x4834, 0xa2, 0x3e, 0x1f, 0x98, 0xf8, 0xfc, 0x52, 0xbe | |
| 0xb54e85d9, 0xfe23, 0x499f, 0x8b, 0x88, 0x6a, 0xce, 0xa7, 0x13, 0x75, 0x2b | |
| 0xa26cec36, 0x234c, 0x4950, 0xae, 0x16, 0xe3, 0x4a, 0xac, 0xe7, 0x1d, 0x0d |
?
This interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
Codecs written as TIFF container formats that are not register will decode as a TIFF image. Client applications should check for a zero frame count to determine if the codec is valid.
-Retrieves the capabilities of the decoder based on the specified stream.
-The stream to retrieve the decoder capabilities from.
The
Custom decoder implementations should save the current position of the specified
Initializes the decoder with the provided stream.
-The stream to use for initialization.
The stream contains the encoded pixels which are decoded each time the CopyPixels method on the
The
If this method succeeds, it returns
Retrieves the image's container format.
-A reference that receives the image's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Copies the decoder's
If this method succeeds, it returns
CopyPalette returns a global palette (a palette that applies to all the frames in the image) if there is one; otherwise, it returns
Retrieves the metadata query reader from the decoder.
-Receives a reference to the decoder's
If this method succeeds, it returns
Retrieves a preview image, if supported.
-Receives a reference to the preview bitmap if supported.
If this method succeeds, it returns
Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a bitmap thumbnail of the image, if one exists
-Receives a reference to the
If this method succeeds, it returns
None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-A reference that receives the total number of frames in the image.
If this method succeeds, it returns
Retrieves the specified frame of the image.
-The particular frame to retrieve.
A reference that receives a reference to the
Retrieves the image's container format.
-Retrieves an
Retrieves the metadata query reader from the decoder.
-Retrieves a preview image, if supported.
-Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves a bitmap thumbnail of the image, if one exists
-None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-Exposes methods that provide information about a decoder.
-Retrieves the file pattern signatures supported by the decoder.
-The array size of the pPatterns array.
Receives a list of
Receives the number of patterns the decoder supports.
Receives the actual buffer size needed to retrieve all pattern signatures supported by the decoder.
If this method succeeds, it returns
To retrieve all pattern signatures, this method should first be called with pPatterns set to
Retrieves a value that indicates whether the codec recognizes the pattern within a specified stream.
-The stream to pattern match within.
A reference that receives TRUE if the patterns match; otherwise,
Creates a new
If this method succeeds, it returns
Defines methods for setting an encoder's properties such as thumbnails, frames, and palettes.
-There are a number of concrete implemenations of this interface representing each of the standard encoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native encoder.
| CLSID Name | CLSID |
|---|---|
| 0x69be8bb4, 0xd66d, 0x47c8, 0x86, 0x5a, 0xed, 0x15, 0x89, 0x43, 0x37, 0x82 | |
| 0x27949969, 0x876a, 0x41d7, 0x94, 0x47, 0x56, 0x8f, 0x6a, 0x35, 0xa4, 0xdc | |
| 0x1a34f5c1, 0x4a5a, 0x46dc, 0xb6, 0x44, 0x1f, 0x45, 0x67, 0xe7, 0xa6, 0x76 | |
| 0x114f5598, 0xb22, 0x40a0, 0x86, 0xa1, 0xc8, 0x3e, 0xa4, 0x95, 0xad, 0xbd | |
| 0x0131be10, 0x2001, 0x4c5f, 0xa9, 0xb0, 0xcc, 0x88, 0xfa, 0xb6, 0x4c, 0xe8 | |
| 0xac4ce3cb, 0xe1c1, 0x44cd, 0x82, 0x15, 0x5a, 0x16, 0x65, 0x50, 0x9e, 0xc2 |
?
Additionally this interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
-Initializes the encoder with an
If this method succeeds, it returns
Retrieves the encoder's container format.
-A reference that receives the encoder's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the global palette for the image.
-The
Returns
Returns
Sets the global thumbnail for the image.
-The
Returns
Returns
Sets the global preview for the image.
-The
Returns
Returns
Creates a new
If this method succeeds, it returns
The parameter ppIEncoderOptions can be used to receive an
Note??Do not pass in a reference to an initialized
Otherwise, you can pass
See Encoding Overview for an example of how to set encoder options.
-Commits all changes for the image and closes the stream.
-If this method succeeds, it returns
To finalize an image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Retrieves a metadata query writer for the encoder.
-When this method returns, contains a reference to the encoder's metadata query writer.
If this method succeeds, it returns
Retrieves the encoder's container format.
-Retrieves an
Sets the global palette for the image.
-Sets the global thumbnail for the image.
-Sets the global preview for the image.
-Retrieves a metadata query writer for the encoder.
-Exposes methods that provide information about an encoder.
-Creates a new
If this method succeeds, it returns
Exposes methods that produce a flipped (horizontal or vertical) and/or rotated (by 90 degree increments) bitmap source. Rotations are done before the flip.
-IWICBitmapFipRotator requests data on a per-pixel basis, while WIC codecs provide data on a per-scanline basis. This causes the fliprotator object to exhibit n2 behavior if there is no buffering. This occures because each pixel in the transformed image requires an entire scanline to be decoded in the file. It is recommended that you buffer the image using
Initializes the bitmap flip rotator with the provided parameters.
-The input bitmap source.
The
If this method succeeds, it returns
Defines methods for decoding individual image frames of an encoded file.
-Retrieves a metadata query reader for the frame.
-When this method returns, contains a reference to the frame's metadata query reader.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a small preview of the frame, if supported by the codec.
-A reference that receives a reference to the
If this method succeeds, it returns
Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Retrieves a metadata query reader for the frame.
-Retrieves a small preview of the frame, if supported by the codec.
-Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Represents an encoder's individual image frames.
-Initializes the frame encoder using the given properties.
-The set of properties to use for
If this method succeeds, it returns
Sets the output image dimensions for the frame.
-The width of the output image.
The height of the output image.
If this method succeeds, it returns
Sets the physical resolution of the output image.
-The horizontal resolution value.
The vertical resolution value.
If this method succeeds, it returns
Requests that the encoder use the specified pixel format.
-If the method succeeds, contains the specified pixel format
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The |
?
Sets a given number
If this method succeeds, it returns
Sets a given number
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-The bitmap source to use as the thumbnail.
Returns
Returns
SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
The size of the pixel buffer.
A reference to the pixel buffer.
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The value of lineCount is larger than the number of scan lines in the image. |
?
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If this method succeeds, it returns
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Commits the frame to the image.
-If this method succeeds, it returns
To finalize the image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Gets the metadata query writer for the encoder frame.
-When this method returns, contains a reference to metadata query writer for the encoder frame.
If this method succeeds, it returns
Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
A reference to the pixel buffer.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Sets the
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Gets the metadata query writer for the encoder frame.
-Exposes methods that support the Lock method.
-The bitmap lock is simply an abstraction for a rectangular memory window into the bitmap. For the simplest case, a system memory bitmap, this is simply a reference to the top left corner of the rectangle and a stride value.
To release the exclusive lock set by Lock method and the associated
Retrieves the width and height, in pixels, of the locked rectangle.
-A reference that receives the width of the locked rectangle.
A reference that receives the height of the locked rectangle.
If this method succeeds, it returns
Provides access to the stride value for the memory.
-If this method succeeds, it returns
Note the stride value is specific to the
Gets the reference to the top left pixel in the locked rectangle.
-A reference that receives the size of the buffer.
A reference that receives a reference to the top left pixel in the locked rectangle.
The reference provided by this method should not be used outside of the lifetime of the lock itself.
GetDataPointer is not available in multi-threaded apartment applications.
-Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-A reference that receives the pixel format
If this method succeeds, it returns
Provides access to the stride value for the memory.
- Note the stride value is specific to the
Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-Represents a resized version of the input bitmap using a resampling or filtering algorithm.
-Images can be scaled to larger sizes; however, even with sophisticated scaling algorithms, there is only so much information in the image and artifacts tend to worsen the more you scale up.
The scaler will reapply the resampling algorithm every time CopyPixels is called. If the scaled image is to be animated, the scaled image should be created once and cached in a new bitmap, after which the
The scaler is optimized to use the minimum amount of memory required to scale the image correctly. The scaler may be used to produce parts of the image incrementally (banding) by calling CopyPixels with different rectangles representing the output bands of the image. Resampling typically requires overlapping rectangles from the source image and thus may need to request the same pixels from the source bitmap multiple times. Requesting scanlines out-of-order from some image decoders can have a significant performance penalty. Because of this reason, the scaler is optimized to handle consecutive horizontal bands of scanlines (rectangle width equal to the bitmap width). In this case the accumulator from the previous vertically adjacent rectangle is re-used to avoid duplicate scanline requests from the source. This implies that banded output from the scaler may have better performance if the bands are requested sequentially. Of course if the scaler is simply used to produce a single rectangle output, this concern is eliminated because the scaler will internally request scanlines in the correct order.
-Initializes the bitmap scaler with the provided parameters.
-The input bitmap source.
The destination width.
The desination height.
The
If this method succeeds, it returns
Copies pixel data using the supplied input parameters.
-The rectangle of pixels to copy.
The width to scale the source bitmap. This parameter must equal the value obtainable through
The height to scale the source bitmap. This parameter must equal the value obtainable through
The
This
The desired rotation or flip to perform prior to the pixel copy.
The transform must be an operation supported by an DoesSupportTransform call.
If a dstTransform is specified, nStride is the transformed stride and is based on the pguidDstFormat pixel format, not the original source's pixel format.
The stride of the destination buffer.
The size of the destination buffer.
The output buffer.
If this method succeeds, it returns
For codec developer implementation details for this method, see Implementing
When multiple transform operations are requested, the result is dependent on the order in which the operations are performed. To ensure predictability and consistency across CODECs, it's important that all CODECs perform these operations in the same order. The recommended order of these operations is:
Pixel format conversion can be performed at any time, since it has no effect on the other transforms.
The first parameter, prc is used to specify the region of interest for clipping the image. By convention, scaling is performed before clipping so, if the image is to be scaled as well as clipped, the region of interest should be determined after the image has been scaled.
If a dstTransform is specified, the stride is the transformed stride, and is based on the pixelFormat specified in the CopyPixels call, not the original frame's pixel format.
-Returns the closest dimensions the implementation can natively scale to given the desired dimensions.
-The desired width. A reference that receives the closest supported width.
The desired height.A reference that receives the closest supported height.
If this method succeeds, it returns
Retrieves the closest pixel format to which the implementation of
If this method succeeds, it returns
Determines whether a specific transform option is supported natively by the implementation of the
If this method succeeds, it returns
Exposes methods for color management.
-A Color Context is an abstraction for a color profile. The profile can be loaded from a file (ie. "sRGB Color Space Profile.icm") or from a memory buffer obtained by reading. The color profile directory can be obtained by calling the GetColorDirectory API (See http://msdn.microsoft.com/library/en-us/icm/icm_58xl.asp).
-Initializes the color context from the given file.
-If this method succeeds, it returns
Initializes the color context from a memory block.
-The buffer used to initialize the
The size of the pbBuffer buffer.
If this method succeeds, it returns
Initializes the color context using an Exchangeable Image File (EXIF) color space.
-The value of the EXIF color space.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
?
If this method succeeds, it returns
Retrieves the color context type.
-A reference that receives the
If this method succeeds, it returns
Retrieves the color context profile.
-The size of the pbBuffer buffer.
A reference that receives the color context profile.
A reference that receives the actual buffer size needed to retrieve the entire color context profile.
If this method succeeds, it returns
Retrieves the Exchangeable Image File (EXIF) color space color context.
-A reference that receives the EXIF color space color context.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
| Unused. |
?
If this method succeeds, it returns
Retrieves the color context type.
-Retrieves the Exchangeable Image File (EXIF) color space color context.
-Exposes methods that transforms an
A
Initializes an
If this method succeeds, it returns
Exposes methods that provide access to the capabilites of a raw codec format.
-Retrieves information about which capabilities are supported for a raw image.
-A reference that receives
If this method succeeds, it returns
It is recommended that a codec report that a capability is supported even if the results at the outer range limits are not of perfect quality.
-Sets the desired
If this method succeeds, it returns
Gets the current set of parameters.
-A reference that receives a reference to the current set of parameters.
If this method succeeds, it returns
Sets the exposure compensation stop value.
-The exposure compensation value. The value range for exposure compensation is -5.0 through +5.0, which equates to 10 full stops.
If this method succeeds, it returns
It is recommended that a codec report that this method is supported even if the results at the outer range limits are not of perfect quality.
-Gets the exposure compensation stop value of the raw image.
-A reference that receives the exposure compensation stop value. The default is the "as-shot" setting.
If this method succeeds, it returns
Sets the white point RGB values.
-The red white point value.
The green white point value.
The blue white point value.
If this method succeeds, it returns
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the white point RGB values.
-A reference that receives the red white point value.
A reference that receives the green white point value.
A reference that receives the blue white point value.
If this method succeeds, it returns
Sets the named white point of the raw file.
-A bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in the API.
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the named white point of the raw image.
-A reference that receives the bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Sets the white point Kelvin value.
-The white point Kelvin value. Acceptable Kelvin values are 1,500 through 30,000.
If this method succeeds, it returns
Codec implementers should faithfully adjust the color temperature within the range supported natively by the raw image. For values outside the native support range, the codec implementer should provide a best effort representation of the image at that color temperature.
Codec implementers should return
Codec implementers must ensure proper interoperability with other white point setting methods such as SetWhitePointRGB. For example, if the caller sets the white point via SetNamedWhitePoint then the codec implementer may want to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wants to deny a given action because of previous calls,
Gets the white point Kelvin temperature of the raw image.
-A reference that receives the white point Kelvin temperature of the raw image. The default is the "as-shot" setting value.
If this method succeeds, it returns
Gets the information about the current Kelvin range of the raw image.
-A reference that receives the minimum Kelvin temperature.
A reference that receives the maximum Kelvin temperature.
A reference that receives the Kelvin step value.
If this method succeeds, it returns
Sets the contrast value of the raw image.
-The contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the contrast value of the raw image.
-A reference that receives the contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
Sets the desired gamma value.
-The desired gamma value.
If this method succeeds, it returns
Gets the current gamma setting of the raw image.
-A reference that receives the current gamma setting.
If this method succeeds, it returns
Sets the sharpness value of the raw image.
-The sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the sharpness value of the raw image.
-A reference that receives the sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
Sets the saturation value of the raw image.
-The saturation value of the raw image. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the saturation value of the raw image.
-A reference that receives the saturation value of the raw image. The default value is the "as-shot" setting. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
Sets the tint value of the raw image.
-The tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
The codec implementer must determine what the outer range values represent and must determine how to map the values to their image processing routines.
-Gets the tint value of the raw image.
-A reference that receives the tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
Sets the noise reduction value of the raw image.
-The noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents highest noise reduction amount that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the noise reduction value of the raw image.
-A reference that receives the noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents full highest noise reduction amount that can be applied.
If this method succeeds, it returns
Sets the destination color context.
-The destination color context.
If this method succeeds, it returns
Sets the tone curve for the raw image.
-The size of the pToneCurve structure.
The desired tone curve.
If this method succeeds, it returns
Gets the tone curve of the raw image.
-The size of the pToneCurve buffer.
A reference that receives the
A reference that receives the size needed to obtain the tone curve structure.
If this method succeeds, it returns
Sets the desired rotation angle.
-The desired rotation angle.
If this method succeeds, it returns
Gets the current rotation angle.
-A reference that receives the current rotation angle.
If this method succeeds, it returns
Sets the current
If this method succeeds, it returns
Gets the current
If this method succeeds, it returns
Sets the notification callback method.
-Pointer to the notification callback method.
If this method succeeds, it returns
Gets the current set of parameters.
-Gets or sets the exposure compensation stop value of the raw image.
-Gets or sets the named white point of the raw image.
-If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Gets or sets the white point Kelvin temperature of the raw image.
-Gets or sets the contrast value of the raw image.
-Gets or sets the current gamma setting of the raw image.
-Gets or sets the sharpness value of the raw image.
-Gets or sets the saturation value of the raw image.
-Gets or sets the tint value of the raw image.
-Gets or sets the noise reduction value of the raw image.
-Sets the destination color context.
-Gets or sets the current rotation angle.
-Gets or sets the current
Sets the notification callback method.
-Flags used to by
An application-defined callback method used for raw image parameter change notifications.
-A set of
If this method succeeds, it returns
Exposes methods that provide enumeration services for individual metadata items.
-Skips to given number of objects.
-The number of objects to skip.
If this method succeeds, it returns
Resets the current position to the beginning of the enumeration.
-If this method succeeds, it returns
Creates a copy of the current
If this method succeeds, it returns
Exposes methods used for in-place metadata editing. A fast metadata encoder enables you to add and remove metadata to an image without having to fully re-encode the image.
- A decoder must be created using the
Not all metadata formats support fast metadata encoding. The native metadata handlers that support metadata are IFD, Exif, XMP, and GPS.
If a fast metadata encoder fails, the image will need to be fully re-encoded to add the metadata.
-Finalizes metadata changes to the image stream.
-If this method succeeds, it returns
If the commit fails and returns
If the commit fails for any reason, you will need to re-encode the image to ensure the new metadata is added to the image.
-Retrieves a metadata query writer for fast metadata encoding.
-When this method returns, contains a reference to the fast metadata encoder's metadata query writer.
If this method succeeds, it returns
Retrieves a metadata query writer for fast metadata encoding.
- Represents an
Initializes the format converter.
-The input bitmap to convert
The destination pixel format
The
The palette to use for conversion.
The alpha threshold to use for conversion.
The palette translation type to use for conversion.
If this method succeeds, it returns
If you do not have a predefined palette, you must first create one. Use InitializeFromBitmap to create the palette object, then pass it in along with your other parameters.
dither, pIPalette, alphaThresholdPercent, and paletteTranslate are used to mitigate color loss when converting to a reduced bit-depth format. For conversions that do not need these settings, the following parameters values should be used: dither set to
The basic algorithm involved when using an ordered dither requires a fixed palette, found in the
If colors in pIPalette do not closely match those in paletteTranslate, the mapping may produce undesireable results.
When converting a bitmap which has an alpha channel, such as a Portable Network Graphics (PNG), to 8bpp, the alpha channel is normally ignored. Any pixels which were transparent in the original bitmap show up as black in the final output because both transparent and black have pixel values of zero in the respective formats.
Some 8bpp content can contains an alpha color; for instance, the Graphics Interchange Format (GIF) format allows for a single palette entry to be used as a transparent color. For this type of content, alphaThresholdPercent specifies what percentage of transparency should map to the transparent color. Because the alpha value is directly proportional to the opacity (not transparency) of a pixel, the alphaThresholdPercent indicates what level of opacity is mapped to the fully transparent color. For instance, 9.8% implies that any pixel with an alpha value of less than 25 will be mapped to the transparent color. A value of 100% maps all pixels which are not fully opaque to the transparent color. Note that the palette should provide a transparent color. If it does not, the 'transparent' color will be the one closest to zero - often black.
-Determines if the source pixel format can be converted to the destination pixel format.
-The source pixel format.
The destionation pixel format.
A reference that receives a value indicating whether the source pixel format can be converted to the destination pixel format.
Exposes methods that provide information about a pixel format converter.
-Retrieves a list of GUIDs that signify which pixel formats the converter supports.
-The size of the pPixelFormatGUIDs array.
Pointer to a
The actual array size needed to retrieve all pixel formats supported by the converter.
If this method succeeds, it returns
The format converter does not necessarily guarantee symmetricality with respect to conversion; that is, a converter may be able to convert FROM a particular format without actually being able to convert TO a particular format. In order to test symmetricality, use CanConvert.
To determine the number of pixel formats a coverter can handle, set cFormats to 0 and pPixelFormatGUIDs to
Creates a new
If this method succeeds, it returns
Exposes methods used to create components for the Windows Imaging Component (WIC) such as decoders, encoders and pixel format converters.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
When a decoder is created using this method, the file handle must remain alive during the lifetime of the decoder.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Other values may be available for both guidContainerFormat and pguidVendor depending on the installed WIC-enabled encoders. The values listed are those that are natively supported by the operating system.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Component types must be enumerated seperately. Combinations of component types and
Creates a new instance of the fast metadata encoder based on the given
If this method succeeds, it returns
The native image formats provided by Windows Imaging Component (WIC) do not support metadata at the decoder level. WIC codecs only support metadata on image frames. To create a fast metadata encoder from an image frame, see the image factory's CreateFastMetadataEncoderFromFrameDecode method.
-Creates a new instance of the fast metadata encoder based on the given image frame.
-The
When this method returns, contains a reference to a new fast metadata encoder.
If this method succeeds, it returns
Creates a new instance of a query writer.
-The
The
When this method returns, contains a reference to a new
If this method succeeds, it returns
Creates a new instance of a query writer based on the given query reader. The query writer will be pre-populated with metadata from the query reader.
-The
The
When this method returns, contains a reference to a new metadata writer.
If this method succeeds, it returns
Exposes methods for retrieving metadata blocks and items from a decoder or its image frames using a metadata query expression.
-A metadata query reader uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Gets the metadata query readers container format.
-Pointer that receives the cointainer format
If this method succeeds, it returns
Retrieves the current path relative to the root metadata block.
-The length of the wzNamespace buffer.
Pointer that receives the current namespace location.
The actual buffer length that was needed to retrieve the current namespace location.
If this method succeeds, it returns
If the query reader is relative to the top of the metadata hierarchy it will return an empty string.
If the query reader is relative to a nested metadata block this method will return the path to the current query reader.
-Retrieves the metadata block or item identified by a metadata query expression.
-The query expression to the requested metadata block or item.
When this method returns, contains the metadata block or item requested.
If this method succeeds, it returns
GetMetadataByName uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If multiple blocks or items exist that are expressed by the same query expression, the first metadata block or item found will be returned.
-Gets an enumerator of all metadata items at the current relative location within the metadata hierachy.
-When this method returns, contais a reference to an enumerator that contains the metadata items.
If a metadata item is a nested metadata block it will be passed back as a VT_UNKNOWN; otherwise, the "name" of the property will be passed back as a VT_LPWSTR. The enumerator does not enumerate content within nested metadata blocks.
Gets the metadata query readers container format.
-Exposes methods for setting or removing metadata blocks and items to an encoder or its image frames using a metadata query expression.
-A metadata query writer uses metadata query expressions to set or remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Sets a metadata item to a specific location.
-The name of the metadata item.
The metadata to set.
If this method succeeds, it returns
SetMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the value set is a nested metadata block then use variant type VT_UNKNOWN and pvarValue pointing to the
Removes a metadata item from a specific location using a metadata query expression.
-The name of the metadata item to remove.
If this method succeeds, it returns
RemoveMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the metadata item is a metadata block, it is removed from the metadata hierarchy.
-Exposes methods for accessing and building a color table, primarily for indexed pixel formats.
-If the
InitializeFromBitmap's fAddTransparentColor parameter will add a transparent color to the end of the color collection if its size if less than 256, otherwise index 255 will be replaced with the transparent color. If a pre-defined palette type is used, it will change to BitmapPaletteTypeCustom since it no longer matches the predefined palette.
The palette interface is an auxiliary imaging interface in that it does not directly concern bitmaps and pixels; rather it provides indexed color translation for indexed bitmaps. For an indexed pixel format with M bits per pixels: (The number of colors in the palette) greater than 2^M.
Traditionally the basic operation of the palette is to provide a translation from a byte (or smaller) index into a 32bpp color value. This is often accomplished by a 256 entry table of color values.
-Initializes the palette to one of the pre-defined palettes specified by
If this method succeeds, it returns
Initializes a palette to the custom color entries provided.
-Pointer to the color array.
The number of colors in pColors.
If this method succeeds, it returns
If a transparent color is required, it should be provided as part of the custom entries.
The entry count is limited to 256.
-Initializes a palette using a computed optimized values based on the reference bitmap.
-Pointer to the source bitmap.
The number of colors to initialize the palette with.
A value to indicate whether to add a transparent color.
If this method succeeds, it returns
The resulting palette contains the specified number of colors which best represent the colors present in the bitmap. The algorithm operates on the opaque RGB color value of each pixel in the reference bitmap and hence ignores any alpha values. If a transparent color is required, set the fAddTransparentColor parameter to TRUE and one fewer optimized color will be computed, reducing the colorCount, and a fully transparent color entry will be added.
-Initialize the palette based on a given palette.
-Pointer to the source palette.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Pointer that receives the number of colors in the color table.
If this method succeeds, it returns
Fills out the supplied color array with the colors from the internal color table. The color array should be sized according to the return results from GetColorCount.
-If this method succeeds, it returns
Retrieves a value that describes whether the palette is black and white.
-Pointer that receives TRUE if the palette is black and white; otherwise,
If this method succeeds, it returns
Retrieves a value that describes whether a palette is grayscale.
-Pointer that receives TRUE if the palette is grayscale; otherwise
If this method succeeds, it returns
Retrieves a value that describes whether the palette contains an alpha transparent color.
-Pointer that receives TRUE if the palette contains a transparent color; otherwise,
If this method succeeds, it returns
Retrieves the
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Retrieves a value that describes whether the palette is black and white.
-Retrieves a value that describes whether a palette is grayscale.
-Exposes methods that provide information about a pixel format.
-Gets the pixel format
Pointer that receives the pixel format
If this method succeeds, it returns
Gets the pixel format's
If this method succeeds, it returns
Gets the bits per pixel (BPP) of the pixel format.
-Pointer that receives the BPP of the pixel format.
If this method succeeds, it returns
Gets the number of channels the pixel format contains.
-Pointer that receives the channel count.
If this method succeeds, it returns
Gets the pixel format's channel mask.
-The index to the channel mask to retrieve.
The size of the pbMaskBuffer buffer.
Pointer to the mask buffer.
The actual buffer size needed to obtain the channel mask.
If this method succeeds, it returns
Gets the pixel format
Gets the pixel format's
Gets the bits per pixel (BPP) of the pixel format.
-Gets the number of channels the pixel format contains.
-Extends
Returns whether the format supports transparent pixels.
-Returns TRUE if the pixel format supports transparency; otherwise, false.
If this method succeeds, it returns
Returns the
If this method succeeds, it returns
Returns whether the format supports transparent pixels.
-Notify method is documented only for compliance; its use is not recommended and may be altered or unavailable in the future. Instead, and use RegisterProgressNotification. -
-If this method succeeds, it returns
Exposes methods for obtaining information about and controlling progressive decoding.
-Images can only be progressively decoded if they were progressively encoded. The native encoders supplied by Windows Imaging Component (WIC) do not
E_NOTIMPL is returned if the codec does not support progressive level decoding.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Indicates the number of levels supported by the CODEC.
If this method succeeds, it returns
Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets the last level set by the SetCurrentLevel call.
-If this method succeeds, it returns
Specifies the level to retrieve on the next call to CopyPixels.
-If this method succeeds, it returns
A call does not have to request every level supported. If a caller requests level 1, without having previously requested level 0, the bits returned by the next call to CopyPixels will include both levels.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets or sets the last level set by the SetCurrentLevel call.
-Represents a Windows Imaging Component (WIC) stream for referencing imaging and metadata content.
-Decoders and metadata handlers are expected to create sub streams of whatever stream they hold when handing off control for embedded metadata to another metadata handler. If the stream is not restricted then use MAXLONGLONG as the max size and offset 0.
The
Initializes a stream from another stream. Access rights are inherited from the underlying stream.
-The initialize stream.
If this method succeeds, it returns
Initializes a stream from a particular file.
-The file used to initialize the stream.
The desired file access mode.
| Value | Meaning |
|---|---|
| Read access. |
| Write access. |
?
If this method succeeds, it returns
The
Initializes a stream to treat a block of memory as a stream. The stream cannot grow beyond the buffer size.
-Pointer to the buffer used to initialize the stream.
The size of buffer.
If this method succeeds, it returns
This method should be avoided whenever possible. The caller is responsible for ensuring the memory block is valid for the lifetime of the stream when using InitializeFromMemory. A workaround for this behavior is to create an
If you require a growable memory stream, use CreateStreamOnHGlobal.
-Initializes the stream as a substream of another stream.
-Pointer to the input stream.
The stream offset used to create the new stream.
The maximum size of the stream.
If this method succeeds, it returns
The stream functions with its own stream position, independent of the underlying stream but restricted to a region. All seek positions are relative to the sub region. It is allowed, though not recommended, to have multiple writable sub streams overlapping the same range.
-Contains members that identify a pattern within an image file which can be used to identify a particular format.
-The offset the pattern is located in the file.
The pattern length.
The actual pattern.
The pattern mask.
The end of the stream.
Defines raw codec capabilites.
-Size of the
The codec's major version.
The codec's minor version.
The
The
The
The
The
The
The
The
The
The
The
The
The
The
The
Represents a raw image tone curve.
-The number of tone curve points.
The array of tone curve points.
Represents a raw image tone curve point.
-The tone curve input.
The tone curve output.
Represents an object that can receive drawing commands. Interfaces that inherit from
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Represents a Direct2D drawing resource.
-Retrieves the factory associated with this resource.
-When this method returns, contains a reference to a reference to the factory that created this resource. This parameter is passed uninitialized.
Retrieves the factory associated with this resource.
-Creates a Direct2D bitmap from a reference to in-memory source data.
-The dimension of the bitmap to create in pixels.
A reference to the memory location of the image data, or
The byte count of each scanline, which is equal to (the image width in pixels ? the number of bytes per pixel) + memory padding. If srcData is
The pixel format and dots per inch (DPI) of the bitmap to create.
When this method returns, contains a reference to a reference to the new bitmap. This parameter is passed uninitialized.
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Before Direct2D can load a WIC bitmap, that bitmap must be converted to a supported pixel format and alpha mode. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.
-Creates an
If this method succeeds, it returns
The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.
Sharing anBy passing an
You may also use this method to reinterpret the data of an existing bitmap and specify a new DPI or alpha mode. For example, in the case of a bitmap atlas, an
When using a DXGI surface render target (an
Note also that the
For more information about interoperability with Direct3D, see the Direct2D and Direct3D Interoperability Overview.
Sharing anAn
To use an
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a layer resource that can be used with this render target and its compatible render targets.
-When the method returns, contains a reference to a reference to the new layer. This parameter is passed uninitialized.
If this method succeeds, it returns
The layer automatically resizes itself, as needed.
-Create a mesh that uses triangles to describe a shape.
-When this method returns, contains a reference to a reference to the new mesh.
If this method succeeds, it returns
To populate a mesh, use its Open method to obtain an
Draws a line between the specified points using the specified stroke style.
-The start point of the line, in device-independent pixels.
The end point of the line, in device-independent pixels.
The brush used to paint the line's stroke.
A value greater than or equal to 0.0f that specifies the width of the stroke. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.
The style of stroke to paint, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the
Draws the outline of a rectangle that has the specified dimensions and stroke style.
-The dimensions of the rectangle to draw, in device-independent pixels.
The brush used to paint the rectangle's stroke.
A value greater than or equal to 0.0f that specifies the width of the rectangle's stroke. The stroke is centered on the rectangle's outline.
The style of stroke to paint, or
When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the
Paints the interior of the specified rectangle.
-The dimension of the rectangle to paint, in device-independent pixels.
The brush used to paint the rectangle's interior.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the
Draws the outline of the specified rounded rectangle using the specified stroke style.
-The dimensions of the rounded rectangle to draw, in device-independent pixels.
The brush used to paint the rounded rectangle's outline.
The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.
The style of the rounded rectangle's stroke, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the
Paints the interior of the specified rounded rectangle.
-The dimensions of the rounded rectangle to paint, in device independent pixels.
The brush used to paint the interior of the rounded rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the
Draws the outline of the specified ellipse using the specified stroke style.
-The position and radius of the ellipse to draw, in device-independent pixels.
The brush used to paint the ellipse's outline.
The thickness of the ellipse's stroke. The stroke is centered on the ellipse's outline.
The style of stroke to apply to the ellipse's outline, or
The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the
Paints the interior of the specified ellipse.
-The position and radius, in device-independent pixels, of the ellipse to paint.
The brush used to paint the interior of the ellipse.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the
Draws the outline of the specified geometry using the specified stroke style.
-The geometry to draw.
The brush used to paint the geometry's stroke.
The thickness of the geometry's stroke. The stroke is centered on the geometry's outline.
The style of stroke to apply to the geometry's outline, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the
Paints the interior of the specified geometry.
-The geometry to paint.
The brush used to paint the geometry's interior.
The opacity mask to apply to the geometry, or
If the opacityBrush parameter is not
When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the
Paints the interior of the specified mesh.
-The mesh to paint.
The brush used to paint the mesh.
The current antialias mode of the render target must be
FillMesh does not expect a particular winding order for the triangles in the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the
For this method to work properly, the render target must be using the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the
Draws the specified bitmap after scaling it to the size of the specified rectangle.
-The bitmap to render.
The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn. If the rectangle is not well-ordered, nothing is drawn, but the render target does not enter an error state.
A value between 0.0f and 1.0f, inclusive, that specifies the opacity value to be applied to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. Default is 1.0f.
The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is
The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to draw;
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the
To draw text with Direct2D, use the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the
Draws the formatted text described by the specified
When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the
Draws the specified glyphs.
-The origin, in device-independent pixels, of the glyphs' baseline.
The glyphs to render.
The brush used to paint the specified glyphs.
A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the
Gets the current transform of the render target.
-When this returns, contains the current transform of the render target. This parameter is passed uninitialized.
Sets the antialiasing mode of the render target. The antialiasing mode applies to all subsequent drawing operations, excluding text and glyph drawing operations.
-The antialiasing mode for future drawing operations.
To specify the antialiasing mode for text and glyph operations, use the SetTextAntialiasMode method.
-Retrieves the current antialiasing mode for nontext drawing operations.
-The current antialiasing mode for nontext drawing operations.
Specifies the antialiasing mode to use for subsequent text and glyph drawing operations.
-The antialiasing mode to use for subsequent text and glyph drawing operations.
Gets the current antialiasing mode for text and glyph drawing operations.
-The current antialiasing mode for text and glyph drawing operations.
Specifies text rendering options to be applied to all subsequent text and glyph drawing operations.
-The text rendering options to be applied to all subsequent text and glyph drawing operations;
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the render target's current text rendering options.
-When this method returns, textRenderingParamscontains the address of a reference to the render target's current text rendering options.
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Specifies a label for subsequent drawing operations.
-A label to apply to subsequent drawing operations.
A label to apply to subsequent drawing operations.
The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.
-Gets the label for subsequent drawing operations.
-When this method returns, contains the first label for subsequent drawing operations. This parameter is passed uninitialized. If
When this method returns, contains the second label for subsequent drawing operations. This parameter is passed uninitialized. If
If the same address is passed for both parameters, both parameters receive the value of the second tag.
-Adds the specified layer to the render target so that it receives all subsequent drawing operations until PopLayer is called.
-The PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.
Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.
A particular
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the
Stops redirecting drawing operations to the layer that is specified by the last PushLayer call.
-A PopLayer must match a previous PushLayer call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the
Executes all pending drawing commands.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
This command does not flush the device that is associated with the render target.
Calling this method resets the error state of the render target.
-Saves the current drawing state to the specified
Sets the render target's drawing state to that of the specified
Specifies a rectangle to which all subsequent drawing operations are clipped.
-The size and position of the clipping area, in device-independent pixels.
The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.
The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.
The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.
Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.
Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.
After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.
The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.
Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.
The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.
A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the
Removes the last axis-aligned clip from the render target. After this method is called, the clip is no longer applied to subsequent drawing operations.
-A PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.
PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.
For an example, see How to Clip with an Axis-Aligned Clip Rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the
Clears the drawing area to the specified color.
-The color to which the drawing area is cleared.
Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is
If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.
-Initiates drawing on this render target.
-Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Ends drawing operations on the render target and indicates the current error state and associated tags.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Retrieves the pixel format and alpha mode of the render target.
-The pixel format and alpha mode of the render target.
Sets the dots per inch (DPI) of the render target.
-A value greater than or equal to zero that specifies the horizontal DPI of the render target.
A value greater than or equal to zero that specifies the vertical DPI of the render target.
This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed.
For
Return the render target's dots per inch (DPI).
-When this method returns, contains the horizontal DPI of the render target. This parameter is passed uninitialized.
When this method returns, contains the vertical DPI of the render target. This parameter is passed uninitialized.
This method indicates the mapping from pixel space to device-independent space for the render target.
For
Returns the size of the render target in device-independent pixels.
-The current size of the render target in device-independent pixels.
Returns the size of the render target in device pixels.
-The size of the render target in device pixels.
Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-The maximum size, in pixels, of any one bitmap dimension supported by the render target.
Indicates whether the render target supports the specified properties.
-The render target properties to test.
TRUE if the specified render target properties are supported by this render target; otherwise,
This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.
-Gets or sets the current transform of the render target.
-Retrieves or sets the current antialiasing mode for nontext drawing operations.
-Gets or sets the current antialiasing mode for text and glyph drawing operations.
-Retrieves or sets the render target's current text rendering options.
-If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the pixel format and alpha mode of the render target.
-Returns the size of the render target in device-independent pixels.
-Returns the size of the render target in device pixels.
-Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
-You create an
if (SUCCEEDED(hr))
- { hr = g_pGdiInterop->CreateBitmapRenderTarget(hdc, r.right, r.bottom, &g_pBitmapRenderTarget);
- }
-
One way to use a
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, DWRITE_MEASURING_MODE measuringMode, __in DWRITE_GLYPH_RUN const* glyphRun, __in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription, IUnknown* clientDrawingEffect )
- { HRESULT hr = S_OK; // Pass on the drawing call to the render target to do the real work. RECT dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;
- }
-
- The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not. Default rendering params can be retrieved by using the Draws a run of glyphs to a bitmap target at the specified position.
-The horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The measuring method for glyphs in the run, used with the other properties to determine the rendering mode.
The structure containing the properties of the glyph run.
The object that controls rendering behavior.
The foreground color of the text.
The optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.
If this method succeeds, it returns
You can use the
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not.
Default rendering params can be retrieved by using the
Gets a handle to the memory device context.
-Returns a device context handle to the memory device context.
An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets the number of bitmap pixels per DIP.
-The number of bitmap pixels per DIP.
A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Sets the number of bitmap pixels per DIP (device-independent pixel). A DIP is 1/96 inch, so this value is the number if pixels per inch divided by 96.
-A value that specifies the number of pixels per DIP.
If this method succeeds, it returns
Gets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-When this method returns, contains a transform matrix.
If this method succeeds, it returns
Sets the transform that maps abstract coordinate to DIPs (device-independent pixel). This does not affect the world transform of the underlying device context.
- Specifies the new transform. This parameter can be
If this method succeeds, it returns
Gets the dimensions of the target bitmap.
-Returns the width and height of the bitmap in pixels.
If this method succeeds, it returns
Resizes the bitmap.
-The new bitmap width, in pixels.
The new bitmap height, in pixels.
If this method succeeds, it returns
Gets a handle to the memory device context.
- An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets or sets the number of bitmap pixels per DIP.
-A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Gets or sets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-Gets the dimensions of the target bitmap.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
- The application implemented rendering callback (
If this method succeeds, it returns
If this method succeeds, it returns
TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object. In the case of a simple bitmap, with no padding and no overhang, all the overhangs will simply be zeroes.
The overhangs should be returned relative to the reported size of the object (see
If this method succeeds, it returns
Layout uses this to determine the line-breaking behavior of the inline object among the text.
-When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately preceding it.
When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately following it.
If this method succeeds, it returns
Used to create all subsequent DirectWrite objects. This interface is the root factory interface for all DirectWrite objects.
- Create an
if (SUCCEEDED(hr))
- { hr = An
Gets an object which represents the set of installed fonts.
-If this parameter is nonzero, the function performs an immediate check for changes to the set of installed fonts. If this parameter is
When this method returns, contains the address of a reference to the system font collection object, or
Creates a font collection using a custom font collection loader.
-An application-defined font collection loader, which must have been previously registered using RegisterFontCollectionLoader.
The key used by the loader to identify a collection of font files. The buffer allocated for this key should at least be the size of collectionKeySize.
The size, in bytes, of the collection key.
Contains an address of a reference to the system font collection object if the method succeeds, or
If this method succeeds, it returns
Registers a custom font collection loader with the factory object.
-Pointer to a
If this method succeeds, it returns
This function registers a font collection loader with DirectWrite. The font collection loader interface, which should be implemented by a singleton object, handles enumerating font files in a font collection given a particular type of key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
-If this method succeeds, it returns
Creates a font file reference object from a local font file.
-An array of characters that contains the absolute file path for the font file. Subsequent operations on the constructed object may fail if the user provided filePath doesn't correspond to a valid file on the disk.
The last modified time of the input file path. If the parameter is omitted, the function will access the font file to obtain its last write time. You should specify this value to avoid extra disk access. Subsequent operations on the constructed object may fail if the user provided lastWriteTime doesn't match the file on the disk.
When this method returns, contains an address of a reference to the newly created font file reference object, or
If this method succeeds, it returns
Creates a reference to an application-specific font file resource.
-A font file reference key that uniquely identifies the font file resource during the lifetime of fontFileLoader.
The size of the font file reference key in bytes.
The font file loader that will be used by the font system to load data from the file identified by fontFileReferenceKey.
Contains an address of a reference to the newly created font file object when this method succeeds, or
If this method succeeds, it returns
This function is provided for cases when an application or a document needs to use a private font without having to install it on the system. fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
-Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates a rendering parameters object with default settings for the primary monitor. Different monitors may have different rendering parameters, for more information see the How to Add Support for Multiple Monitors topic.
-Standard
Creates a rendering parameters object with default settings for the specified monitor. In most cases, this is the preferred way to create a rendering parameters object.
-A handle for the specified monitor.
When this method returns, contains an address of a reference to the rendering parameters object created by this method.
If this method succeeds, it returns
Creates a rendering parameters object with the specified properties.
-The gamma level to be set for the new rendering parameters object.
The enhanced contrast level to be set for the new rendering parameters object.
The ClearType level to be set for the new rendering parameters object.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.
A value that represents the method (for example, ClearType natural quality) for rendering glyphs.
When this method returns, contains an address of a reference to the newly created rendering parameters object.
If this method succeeds, it returns
Registers a font file loader with DirectWrite.
-Pointer to a
If this method succeeds, it returns
This function registers a font file loader with DirectWrite. The font file loader interface, which should be implemented by a singleton object, handles loading font file resources of a particular type from a key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
-If this method succeeds, it returns
This function unregisters font file loader callbacks with the DirectWrite font system. You should implement the font file loader interface by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite should be performed outside of the font file loader implementation.
-Creates a text format object used for text layout.
-An array of characters that contains the name of the font family
A reference to a font collection object. When this is
A value that indicates the font weight for the text object created by this method.
A value that indicates the font style for the text object created by this method.
A value that indicates the font stretch for the text object created by this method.
The logical size of the font in DIP ("device-independent pixel") units. A DIP equals 1/96 inch.
An array of characters that contains the locale name.
When this method returns, contains an address of a reference to a newly created text format object, or
If this method succeeds, it returns
Creates a typography object for use in a text layout.
-When this method returns, contains the address of a reference to a newly created typography object, or
If this method succeeds, it returns
Creates an object that is used for interoperability with GDI.
-When this method returns, contains an address of a reference to a GDI interop object if successful, or
If this method succeeds, it returns
Takes a string, text format, and associated constraints, and produces an object that represents the fully analyzed and formatted result.
-An array of characters that contains the string to create a new
The number of characters in the string.
A reference to an object that indicates the format to apply to the string.
The width of the layout box.
The height of the layout box.
When this method returns, contains an address of a reference to the resultant text layout object.
If this method succeeds, it returns
Takes a string, format, and associated constraints, and produces an object representing the result, formatted for a particular display resolution and measuring mode.
-An array of characters that contains the string to create a new
The length of the string, in character count.
The text formatting object to apply to the string.
The width of the layout box.
The height of the layout box.
The number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI device pixelsPerDip is 1. If rendering onto a 120 DPI device pixelsPerDip is 1.25 (120/96).
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specifies the font size and pixels per DIP.
Instructs the text layout to use the same metrics as GDI bi-level text when set to
When this method returns, contains an address to the reference of the resultant text layout object.
If this method succeeds, it returns
The resulting text layout should only be used for the intended resolution, and for cases where text scalability is desired CreateTextLayout should be used instead.
-Creates an inline object for trimming, using an ellipsis as the omission sign.
-A text format object, created with CreateTextFormat, used for text layout.
When this method returns, contains an address of a reference to the omission (that is, ellipsis trimming) sign created by this method.
If this method succeeds, it returns
The ellipsis will be created using the current settings of the format, including base font, style, and any effects. Alternate omission signs can be created by the application by implementing
Returns an interface for performing text analysis.
-When this method returns, contains an address of a reference to the newly created text analyzer object.
If this method succeeds, it returns
Creates a number substitution object using a locale name, substitution method, and an indicator whether to ignore user overrides (use NLS defaults for the given culture instead).
-A value that specifies how to apply number substitution on digits and related punctuation.
The name of the locale to be used in the numberSubstitution object.
A Boolean flag that indicates whether to ignore user overrides.
When this method returns, contains an address to a reference to the number substitution object created by this method.
If this method succeeds, it returns
Creates a glyph run analysis object, which encapsulates information used to render a glyph run.
-A structure that contains the properties of the glyph run (font face, advances, and so on).
Number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI bitmap then pixelsPerDip is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 1.25.
Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified the emSize and pixelsPerDip.
A value that specifies the rendering mode, which must be one of the raster rendering modes (that is, not default and not outline).
Specifies the measuring mode to use with glyphs.
The horizontal position (X-coordinate) of the baseline origin, in DIPs.
Vertical position (Y-coordinate) of the baseline origin, in DIPs.
When this method returns, contains an address of a reference to the newly created glyph run analysis object.
If this method succeeds, it returns
The glyph run analysis object contains the results of analyzing the glyph run, including the positions of all the glyphs and references to all of the rasterized glyphs in the font cache.
-Creates an object that is used for interoperability with GDI.
-An object that encapsulates a set of fonts, such as the set of fonts installed on the system, or the set of fonts in a particular directory. The font collection API can be used to discover what font families and fonts are available, and to obtain some metadata about the fonts.
-The
null ; // Get the system font collection.
- if (SUCCEEDED(hr))
- { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection);
- }
-
To determine what fonts are available on the system, get a reference to the system font collection. You can then use the
#include <dwrite.h>
- #include <string.h>
- #include <stdio.h>
- #include <new> // SafeRelease inline function.
- template <class T> inline void SafeRelease(T **ppT)
- { if (*ppT) { (*ppT)->Release(); *ppT = null ; }
- } void wmain()
- { null ; null ; // Get the system font collection. if (SUCCEEDED(hr)) { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection); } UINT32 familyCount = 0; // Get the number of font families in the collection. if (SUCCEEDED(hr)) { familyCount = pFontCollection->GetFontFamilyCount(); } for (UINT32 i = 0; i < familyCount; ++i) { null ; // Get the font family. if (SUCCEEDED(hr)) { hr = pFontCollection->GetFontFamily(i, &pFontFamily); } null ; // Get a list of localized strings for the family name. if (SUCCEEDED(hr)) { hr = pFontFamily->GetFamilyNames(&pFamilyNames); } UINT32 index = 0; null ) { hr = E_OUTOFMEMORY; } // Get the family name. if (SUCCEEDED(hr)) { hr = pFamilyNames->GetString(index, name, length+1); } if (SUCCEEDED(hr)) { // Print out the family name. wprintf(L"%s\n", name); } SafeRelease(&pFontFamily); SafeRelease(&pFamilyNames); delete [] name; } SafeRelease(&pFontCollection); SafeRelease(&pDWriteFactory);
- } Gets the number of font families in the collection.
-The number of font families in the collection.
Creates a font family object given a zero-based font family index.
-Zero-based index of the font family.
When this method returns, contains the address of a reference to the newly created font family object.
Finds the font family with the specified family name.
-An array of characters, which is null-terminated, containing the name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.
When this method returns, contains the zero-based index of the matching font family if the family name was found; otherwise, UINT_MAX.
When this method returns, TRUE if the family name exists; otherwise,
Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong to the font collection.
-A font face object that specifies the physical font.
When this method returns, contains the address of a reference to the newly created font object if successful; otherwise,
Gets the number of font families in the collection.
-Used to construct a collection of fonts given a particular type of key.
-The font collection loader interface is recommended to be implemented by a singleton object. Note that font collection loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Represents an absolute reference to a font face which contains font face type, appropriate file references, face identification data and various font data such as metrics, names and glyph outlines.
-Obtains the file format type of a font face.
-A value that indicates the type of format for the font face (such as Type 1, TrueType, vector, or bitmap).
Obtains the font files representing a font face.
-If fontFiles is
When this method returns, contains a reference to a user-provided array that stores references to font files representing the font face. This parameter can be
If this method succeeds, it returns
The
Then, call the method a second time, passing the numberOfFiles value that was output the first call, and a non-null buffer of the correct size to store the
Obtains the index of a font face in the context of its font files.
-The zero-based index of a font face in cases when the font files contain a collection of font faces. If the font files contain a single face, this value is zero.
Obtains the algorithmic style simulation flags of a font face.
-Font face simulation flags for algorithmic means of making text bold or italic.
Determines whether the font is a symbol font.
-Returns TRUE if the font is a symbol font, otherwise
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, a?
Obtains the number of glyphs in the font face.
-The number of glyphs in the font face.
Obtains ideal (resolution-independent) glyph metrics in font design units.
-An array of glyph indices for which to compute metrics. The array must contain at least as many elements as specified by glyphCount.
The number of elements in the glyphIndices array.
When this method returns, contains an array of
Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation
If this method succeeds, it returns
Design glyph metrics are used for glyph positioning.
-Returns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.
-An array of USC4 code points from which to obtain nominal glyph indices. The array must be allocated and be able to contain the number of elements specified by codePointCount.
The number of elements in the codePoints array.
When this method returns, contains a reference to an array of nominal glyph indices filled by this function.
If this method succeeds, it returns
Note that this mapping is primarily provided for line layout engines built on top of the physical font API. Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond to how a Unicode string will map to glyph indices when rendering using a particular font face. Also, note that Unicode variant selectors provide for alternate mappings for character to glyph. This call will always return the default variant.
- Finds the specified OpenType font table if it exists and returns a reference to it. The function accesses the underlying font data through the
If this method succeeds, it returns
The context for the same tag may be different for each call, so each one must be held and released separately.
-Releases the table obtained earlier from TryGetFontTable.
-Computes the outline of a run of glyphs by calling back to the outline sink interface.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
An array of glyph indices. The glyphs are in logical order and the advance direction depends on the isRightToLeft parameter. The array must be allocated and be able to contain the number of elements specified by glyphCount.
An optional array of glyph advances in DIPs. The advance of a glyph is the amount to advance the position (in the direction of the baseline) after drawing the glyph. glyphAdvances contains the number of elements specified by glyphCount.
An optional array of glyph offsets, each of which specifies the offset along the baseline and offset perpendicular to the baseline of a glyph relative to the current pen position. glyphOffsets contains the number of elements specified by glyphCount.
The number of glyphs in the run.
If TRUE, the ascender of the glyph runs alongside the baseline. If
A client can render a vertical run by setting isSideways to TRUE and rotating the resulting geometry 90 degrees to the right using a transform. The isSideways and isRightToLeft parameters cannot both be true.
The visual order of the glyphs. If this parameter is
A reference to the interface that is called back to perform outline drawing operations.
If this method succeeds, it returns
Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
The number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:
A reference to an object that contains rendering settings such as gamma level, enhanced contrast, and ClearType level. This parameter is necessary in case the rendering parameters object overrides the rendering mode.
When this method returns, contains a value that indicates the recommended rendering mode to use.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
-The logical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
A reference to a DWRITE_FONT_METRICS structure to fill in. The metrics returned by this function are in font design units.
Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.
-The ogical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
When set to
An array of glyph indices for which to compute the metrics.
The number of elements in the glyphIndices array.
An array of
A
Standard
Obtains the file format type of a font face.
-Obtains the index of a font face in the context of its font files.
-Obtains the algorithmic style simulation flags of a font face.
-Determines whether the font is a symbol font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Obtains the number of glyphs in the font face.
-Specifies properties used to identify and execute typographic features in the current font face.
-A non-zero value generally enables the feature execution, while the zero value disables it. A feature requiring a selector uses this value to indicate the selector index.
The OpenType standard provides access to typographic features available in the font by means of a feature tag with the associated parameters. The OpenType feature tag is a 4-byte identifier of the registered name of a feature. For example, the 'kern' feature name tag is used to identify the 'Kerning' feature in OpenType font. Similarly, the OpenType feature tag for 'Standard Ligatures' and 'Fractions' is 'liga' and 'frac' respectively. Since a single run can be associated with more than one typographic features, the Text String API accepts typographic settings for a run as a list of features and are executed in the order they are specified.
The value of the tag member represents the OpenType name tag of the feature, while the param value represents additional parameter for the execution of the feature referred by the tag member. Both nameTag and parameter are stored as little endian, the same convention followed by GDI. Most features treat the Param value as a binary value that indicates whether to turn the execution of the feature on or off, with it being off by default in the majority of cases. Some features, however, treat this value as an integral value representing the integer index to the list of alternate results it may produce during the execution; for instance, the feature 'Stylistic Alternates' or 'salt' uses the parameter value as an index to the list of alternate substituting glyphs it could produce for a specified glyph.
-The feature OpenType name identifier.
The execution parameter of the feature.
Represents a font file. Applications such as font managers or font viewers can call
Obtains the reference to the reference key of a font file. The returned reference is valid until the font file object is released.
-When this method returns, contains an address of a reference to the font file reference key. Note that the reference value is only valid until the font file object it is obtained from is released. This parameter is passed uninitialized.
When this method returns, contains the size of the font file reference key in bytes. This parameter is passed uninitialized.
If this method succeeds, it returns
Obtains the file loader associated with a font file object.
-When this method returns, contains the address of a reference to the font file loader associated with the font file object.
If this method succeeds, it returns
Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
-TRUE if the font type is supported by the font system; otherwise,
When this method returns, contains a value that indicates the type of the font file. Note that even if isSupportedFontType is
When this method returns, contains a value that indicates the type of the font face. If fontFileType is not equal to
When this method returns, contains the number of font faces contained in the font file.
If this method succeeds, it returns
Important??Certain font file types are recognized, but not supported by the font system. For example, the font system will recognize a file as a Type 1 font file but will not be able to construct a font face object from it. In such situations, Analyze will set isSupportedFontType output parameter to
Encapsulates a collection of font files. The font system uses this interface to enumerate font files when building a font collection.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Creates a font file stream object that encapsulates an open file resource.
-A reference to a font file reference key that uniquely identifies the font file resource within the scope of the font loader being used. The buffer allocated for this key must at least be the size, in bytes, specified by fontFileReferenceKeySize.
The size of font file reference key, in bytes.
When this method returns, contains the address of a reference to the newly created
If this method succeeds, it returns
The resource is closed when the last reference to fontFileStream is released.
-Loads font file data from a custom font file loader.
-Loads font file data from a custom font file loader.
-Reads a fragment from a font file.
-When this method returns, contains an address of a reference to the start of the font file fragment. This parameter is passed uninitialized.
The offset of the fragment, in bytes, from the beginning of the font file.
The size of the file fragment, in bytes.
When this method returns, contains the address of a reference to a reference to the client-defined context to be passed to ReleaseFileFragment.
If this method succeeds, it returns
Note that ReadFileFragment implementations must check whether the requested font file fragment is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
DirectWrite may invoke
Releases a fragment from a file.
-A reference to the client-defined context of a font fragment returned from ReadFileFragment.
Obtains the total size of a file.
-When this method returns, contains the total size of the file.
If this method succeeds, it returns
Implementing GetFileSize() for asynchronously loaded font files may require downloading the complete file contents. Therefore, this method should be used only for operations that either require a complete font file to be loaded (for example, copying a font file) or that need to make decisions based on the value of the file size (for example, validation against a persisted file size).
-Obtains the last modified time of the file.
-When this method returns, contains the last modified time of the file in the format that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC).
If this method succeeds, it returns
The "last modified time" is used by DirectWrite font selection algorithms to determine whether one font resource is more up to date than another one.
-Provides interoperability with GDI, such as methods to convert a font face to a
Creates a font object that matches the properties specified by the
A structure containing a GDI-compatible font description.
When this method returns, contains an address of a reference to a newly created
If this method succeeds, it returns
Initializes a
An
When this method returns, contains a structure that receives a GDI-compatible font description.
When this method returns, contains TRUE if the specified font object is part of the system font collection; otherwise,
If this method succeeds, it returns
The conversion to a
Initializes a
An
When this method returns, contains a reference to a structure that receives a GDI-compatible font description.
If this method succeeds, it returns
The conversion to a
Creates an
A handle to a device context into which a font has been selected. It is assumed that the client has already performed font mapping and that the font selected into the device context is the actual font to be used for rendering glyphs.
Contains an address of a reference to the newly created font face object, or
This function is intended for scenarios in which an application wants to use GDI and Uniscribe 1.x for text layout and shaping, but DirectWrite for final rendering. This function assumes the client is performing text output using glyph indexes.
-Creates an object that encapsulates a bitmap and memory DC (device context) which can be used for rendering glyphs.
-A handle to the optional device context used to create a compatible memory DC (device context).
The width of the bitmap render target.
The height of the bitmap render target.
When this method returns, contains an address of a reference to the newly created
Contains the information needed by renderers to draw glyph runs. All coordinates are in device independent pixels (DIPs).
-The physical font face object to draw with.
The logical size of the font in DIPs (equals 1/96 inch), not points.
The number of glyphs in the glyph run.
A reference to an array of indices to render for the glyph run.
A reference to an array containing glyph advance widths for the glyph run.
A reference to an array containing glyph offsets for the glyph run.
If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used. Vertical writing is achieved by specifying isSideways = true and rotating the entire run 90 degrees to the right via a rotate transform.
The implicit resolved bidi level of the run. Odd levels indicate right-to-left languages like Hebrew and Arabic, while even levels indicate left-to-right languages like English and Japanese (when written horizontally). For right-to-left languages, the text origin is on the right, and text should be drawn to the left.
Contains low-level information used to render a glyph run.
-The alpha texture can be a bi-level alpha texture or a ClearType alpha texture.
A bi-level alpha texture contains one byte per pixel, therefore the size of the buffer for a bi-level texture will be the area of the texture bounds, in bytes. Each byte in a bi-level alpha texture created by CreateAlphaTexture is either set to DWRITE_ALPHA_MAX (that is, 255) or zero.
A ClearType alpha texture contains three bytes per pixel, therefore the size of the buffer for a ClearType alpha texture is three times the area of the texture bounds, in bytes.
-Gets the bounding rectangle of the physical pixels affected by the glyph run.
-Specifies the type of texture requested. If a bi-level texture is requested, the bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only antialiased glyphs.
When this method returns, contains the bounding rectangle of the physical pixels affected by the glyph run, or an empty rectangle if there are no glyphs of the specified texture type.
Creates an alpha texture of the specified type for glyphs within a specified bounding rectangle.
-A value that specifies the type of texture requested. This can be DWRITE_TEXTURE_BILEVEL_1x1 or
The bounding rectangle of the texture, which can be different than the bounding rectangle returned by GetAlphaTextureBounds.
When this method returns, contains the array of alpha values from the texture. The buffer allocated for this array must be at least the size of bufferSize.
The size of the alphaValues array, in bytes. The minimum size depends on the dimensions of the rectangle and the type of texture requested.
If this method succeeds, it returns
Gets alpha blending properties required for ClearType blending.
-An object that specifies the ClearType level and enhanced contrast, gamma, pixel geometry, and rendering mode. In most cases, the values returned by the output parameters of this method are based on the properties of this object, unless a GDI-compatible rendering mode was specified.
When this method returns, contains the gamma value to use for gamma correction.
When this method returns, contains the enhanced contrast value to be used for blending.
When this method returns, contains the ClearType level used in the alpha blending.
If this method succeeds, it returns
Contains additional properties related to those in
An array of characters containing the locale name associated with this run.
An array of characters containing the text associated with the glyphs.
The number of characters in UTF16 code-units. Note that this may be different than the number of glyphs.
An array of indices to the glyph indices array, of the first glyphs of all the glyph clusters of the glyphs to render.
Corresponding text position in the string this glyph run came from. This is relative to the beginning of the string represented by the
Line breakpoint characteristics of a character.
-Indicates a breaking condition before the character.
Indicates a breaking condition after the character.
Indicates that the character is some form of whitespace, which may be meaningful for justification.
Indicates that the character is a soft hyphen, often used to indicate hyphenation points inside words.
Reserved for future use.
Represents a collection of strings indexed by locale name.
-The set of strings represented by an
A common use for the
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-The number of language/string pairs.
Gets the zero-based index of the locale name/string pair with the specified locale name.
-A null-terminated array of characters containing the locale name to look for.
The zero-based index of the locale name/string pair. This method initializes index to UINT_MAX.
When this method returns, contains TRUE if the locale name exists; otherwise,
Note that if the locale name does not exist, the return value is a success and the exists parameter is
UINT32 index = 0;
- Gets the length in characters (not including the null terminator) of the locale name with the specified index.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains the length in characters of the locale name, not including the null terminator.
If this method succeeds, it returns
Copies the locale name with the specified index to the specified array.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains a character array, which is null-terminated, that receives the locale name from the language/string pair. The buffer allocated for this array must be at least the size of size, in element count.
The size of the array in characters. The size must include space for the terminating null character.
If this method succeeds, it returns
Gets the length in characters (not including the null terminator) of the string with the specified index.
-A zero-based index of the language/string pair.
The length in characters of the string, not including the null terminator, from the language/string pair.
If this method succeeds, it returns
Use GetStringLength to get the string length before calling the
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Copies the string with the specified index to the specified array.
-The zero-based index of the language/string pair to be examined.
The null terminated array of characters that receives the string from the language/string pair. The buffer allocated for this array should be at least the size of size. GetStringLength can be used to get the size of the array before using this method.
The size of the array in characters. The size must include space for the terminating null character. GetStringLength can be used to get the size of the array before using this method.
If this method succeeds, it returns
The string returned must be allocated by the caller. You can get the size of the string by using the GetStringLength method prior to calling GetString, as shown in the following example.
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-Holds the appropriate digits and numeric punctuation for a specified locale.
-Defines the pixel snapping properties such as pixels per DIP(device-independent pixel) and the current transform matrix of a text renderer.
-Represents text rendering settings such as ClearType level, enhanced contrast, and gamma correction for glyph rasterization and filtering.
An application typically obtains a rendering parameters object by calling the
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-Returns the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Returns the amount of contrast enhancement. Valid values are greater than or equal to zero.
Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level of the rendering parameters object.
The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-A value that indicates the type of pixel geometry used in the rendering parameters object.
Gets the rendering mode of the rendering parameters object.
-A value that indicates the rendering mode of the rendering parameters object.
By default, the rendering mode is initialized to
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-Gets the rendering mode of the rendering parameters object.
-By default, the rendering mode is initialized to
Contains shaping output properties for an output glyph.
-Indicates that the glyph has justification applied.
Indicates that the glyph is the start of a cluster.
Indicates that the glyph is a diacritic mark.
Indicates that the glyph is a word boundary with no visible space.
Reserved for future use.
This interface is implemented by the text analyzer's client to receive the output of a given text analysis.
-The text analyzer disregards any current state of the analysis sink, therefore, a Set method call on a range overwrites the previously set analysis result of the same range.
-Implemented by the text analyzer's client to provide text to the analyzer. It allows the separation between the logical view of text as a continuous stream of characters identifiable by unique text positions, and the actual memory layout of potentially discrete blocks of text in the client's backing store.
-If any of these callbacks returns an error, then the analysis functions will stop prematurely and return a callback error. Note that rather than return E_NOTIMPL, an application should stub the method and return a constant/null and
Analyzes various text properties for complex script processing such as bidirectional (bidi) support for languages like Arabic, determination of line break opportunities, glyph placement, and number substitution.
-Analyzes a text range for script boundaries, reading text attributes from the source and reporting the Unicode script ID to the sink callback SetScript.
-If this method succeeds, it returns
Analyzes a text range for script directionality, reading attributes from the source and reporting levels to the sink callback SetBidiLevel.
-If this method succeeds, it returns
While the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs. Otherwise, the returned levels may be wrong, because the Bidi algorithm is meant to apply to the paragraph as a whole.
-Analyzes a text range for spans where number substitution is applicable, reading attributes from the source and reporting substitutable ranges to the sink callback SetNumberSubstitution.
-If this method succeeds, it returns
Although the function can handle multiple ranges of differing number substitutions, the text ranges should not arbitrarily split the middle of numbers. Otherwise, it will treat the numbers separately and will not translate any intervening punctuation.
-Analyzes a text range for potential breakpoint opportunities, reading attributes from the source and reporting breakpoint opportunities to the sink callback SetLineBreakpoints.
-If this method succeeds, it returns
Although the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs, unless the specified text span is considered a whole unit. Otherwise, the returned properties for the first and last characters will inappropriately allow breaks.
-Parses the input text string and maps it to the set of glyphs and associated glyph data according to the font and the writing system's rendering rules.
-An array of characters to convert to glyphs.
The length of textString.
The font face that is the source of the output glyphs.
A Boolean flag set to TRUE if the text is intended to be drawn vertically.
A Boolean flag set to TRUE for right-to-left text.
A reference to a Script analysis result from an AnalyzeScript call.
The locale to use when selecting glyphs. For example the same character may map to different glyphs for ja-jp versus zh-chs. If this is
A reference to an optional number substitution which selects the appropriate glyphs for digits and related numeric characters, depending on the results obtained from AnalyzeNumberSubstitution. Passing
An array of references to the sets of typographic features to use in each feature range.
The length of each feature range, in characters. The sum of all lengths should be equal to textLength.
The number of feature ranges.
The maximum number of glyphs that can be returned.
When this method returns, contains the mapping from character ranges to glyph ranges.
When this method returns, contains a reference to an array of structures that contains shaping properties for each character.
The output glyph indices.
When this method returns, contains a reference to an array of structures that contain shaping properties for each output glyph.
When this method returns, contains the actual number of glyphs returned if the call succeeds.
If this method succeeds, it returns
Note that the mapping from characters to glyphs is, in general, many-to-many. The recommended estimate for the per-glyph output buffers is (3 * textLength / 2 + 16). This is not guaranteed to be sufficient. The value of the actualGlyphCount parameter is only valid if the call succeeds. In the event that maxGlyphCount is not big enough, HRESULT_FROM_WIN32(
Places glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
Place glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
The
To get a reference to the
if (SUCCEEDED(hr))
- { hr = pDWriteFactory_->CreateTextFormat( L"Gabriola", null , When creating an
These properties cannot be changed after the
The
To draw text with multiple formats, or to use a custom text renderer, use the
This object may not be thread-safe, and it may carry the state of text format change.
DirectWrite and Direct2D To draw simple text with a single format, Direct2D provides the
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the alignment of text in a paragraph, relative to the leading and trailing edge of a layout box for a
This method can return one of the following values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| The textAlignment argument is invalid. |
?
The text can be aligned to the leading or trailing edge of the layout box, or it can be centered. The following illustration shows text with the alignment set to
Note??The alignment is dependent on reading direction, the above is for left-to-right reading direction. For right-to-left reading direction it would be the opposite.
See
Sets the alignment option of a paragraph relative to the layout box's top and bottom edge.
-The paragraph alignment option being set for a paragraph; see
If this method succeeds, it returns
Sets the word wrapping option.
-The word wrapping option being set for a paragraph; see
If this method succeeds, it returns
Sets the paragraph reading direction.
-The text reading direction (for example,
If this method succeeds, it returns
Sets the paragraph flow direction.
-The paragraph flow direction; see
If this method succeeds, it returns
Sets a fixed distance between two adjacent tab stops.
-The fixed distance between two adjacent tab stops.
If this method succeeds, it returns
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the line spacing.
-Specifies how line height is being determined; see
The line height, or distance between one baseline to another.
The distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
For the default method, spacing depends solely on the content. For uniform spacing, the specified line height overrides the content.
-Gets the alignment option of text relative to the layout box's leading and trailing edge.
-Returns the text alignment option of the current paragraph.
Gets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-A value that indicates the current paragraph alignment option.
Gets the word wrapping option.
-Returns the word wrapping option; see
Gets the current reading direction for text in a paragraph.
-A value that indicates the current reading direction for text in a paragraph.
Gets the direction that text lines flow.
-The direction that text lines flow within their parent container. For example,
Gets the incremental tab stop position.
-The incremental tab stop value.
Gets the trimming options for text that overflows the layout box.
-When this method returns, it contains a reference to a
When this method returns, contains an address of a reference to a trimming omission sign. This parameter may be
If this method succeeds, it returns
Gets the line spacing adjustment set for a multiline text paragraph.
-A value that indicates how line height is determined.
When this method returns, contains the line height, or distance between one baseline to another.
When this method returns, contains the distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
Gets the current font collection.
-When this method returns, contains an address of a reference to the font collection being used for the current text.
If this method succeeds, it returns
Gets the length of the font family name.
-The size of the character array, in character count, not including the terminated
Gets a copy of the font family name.
-When this method returns, contains a reference to a character array, which is null-terminated, that receives the current font family name. The buffer allocated for this array should be at least the size, in elements, of nameSize.
The size of the fontFamilyName character array, in character count, including the terminated
If this method succeeds, it returns
Gets the font weight of the text.
-A value that indicates the type of weight (such as normal, bold, or black).
Gets the font style of the text.
-A value which indicates the type of font style (such as slope or incline).
Gets the font stretch of the text.
-A value which indicates the type of font stretch (such as normal or condensed).
Gets the font size in DIP unites.
-The current font size in DIP units.
Gets the length of the locale name.
-The size of the character array in character count, not including the terminated
Gets a copy of the locale name.
-Contains a character array that receives the current locale name.
The size of the character array, in character count, including the terminated
If this method succeeds, it returns
Gets or sets the alignment option of text relative to the layout box's leading and trailing edge.
-Gets or sets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-Gets or sets the word wrapping option.
-Gets or sets the current reading direction for text in a paragraph.
-Gets or sets the direction that text lines flow.
-Gets or sets the incremental tab stop position.
-Gets the current font collection.
-Gets the font weight of the text.
-Gets the font style of the text.
-Gets the font stretch of the text.
-Gets the font size in DIP unites.
-The
To get a reference to the
// Create a text layout using the text format.
- if (SUCCEEDED(hr))
- { The
// Set the font weight to bold for the first 5 letters.
- To draw the block of text represented by an
To draw a formatted string represented by an
To render using a custom renderer, use the
// Draw the text layout using DirectWrite and the CustomTextRenderer class.
- hr = pTextLayout_->Draw( null , pTextRenderer_, // Custom text renderer. origin.x, origin.y );
Using a custom text renderer also enables you to render using another technology, such as GDI.
-Sets the layout maximum width.
-A value that indicates the maximum width of the layout box.
If this method succeeds, it returns
Sets the layout maximum height.
-A value that indicates the maximum height of the layout box.
If this method succeeds, it returns
Sets the font collection.
-The font collection to set.
Text range to which this change applies.
If this method succeeds, it returns
Sets null-terminated font family name for text within a specified text range.
-The font family name that applies to the entire text string within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font weight for text within a text range specified by a
If this method succeeds, it returns
The font weight can be set to one of the predefined font weight values provided in the
The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
- Sets the font style for text within a text range specified by a
If this method succeeds, it returns
The font style can be set to Normal, Italic or Oblique. The following illustration shows three styles for the Palatino font. For more information, see
Sets the font stretch for text within a specified text range.
-A value which indicates the type of font stretch for text within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font size in DIP units for text within a specified text range.
-The font size in DIP units to be set for text in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets underlining for text within a specified text range.
-A Boolean flag that indicates whether underline takes place within a specified text range.
Text range to which this change applies.
If this method succeeds, it returns
Sets strikethrough for text within a specified text range.
-A Boolean flag that indicates whether strikethrough takes place in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the application-defined drawing effect.
-Application-defined drawing effects that apply to the range. This data object will be passed back to the application's drawing callbacks for final rendering.
The text range to which this change applies.
If this method succeeds, it returns
An
This drawing effect is associated with the specified range and will be passed back to the application by way of the callback when the range is drawn at drawing time.
-Sets the inline object.
-An application-defined inline object.
Text range to which this change applies.
If this method succeeds, it returns
The application may call this function to specify the set of properties describing an application-defined inline object for specific range.
This inline object applies to the specified range and will be passed back to the application by way of the DrawInlineObject callback when the range is drawn. Any text in that range will be suppressed.
-Sets font typography features for text within a specified text range.
-Pointer to font typography settings.
Text range to which this change applies.
If this method succeeds, it returns
Sets the locale name for text within a specified text range.
-A null-terminated locale name string.
Text range to which this change applies.
If this method succeeds, it returns
Gets the layout maximum width.
-Returns the layout maximum width.
Gets the layout maximum height.
-The layout maximum height.
Gets the font collection associated with the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
Contains an address of a reference to the current font collection.
Get the length of the font family name at the current position.
-The current text position.
When this method returns, contains the size of the character array containing the font family name, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family.
If this method succeeds, it returns
Copies the font family name of the text at the specified position.
-The position of the text to examine.
When this method returns, contains an array of characters that receives the current font family name. You must allocate storage for this parameter.
The size of the character array in character count including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family name.
If this method succeeds, it returns
Gets the font weight of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font weight.
When this method returns, contains a value which indicates the type of font weight being applied at the specified position.
Gets the font style (also known as slope) of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font style.
When this method returns, contains a value which indicates the type of font style (also known as slope or incline) being applied at the specified position.
Gets the font stretch of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font stretch.
When this method returns, contains a value which indicates the type of font stretch (also known as width) being applied at the specified position.
Gets the font em height of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font size.
When this method returns, contains the size of the font in ems of the text at the specified position.
Gets the underline presence of the text at the specified position.
-The current text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
A Boolean flag that indicates whether underline is present at the position indicated by currentPosition.
Get the strikethrough presence of the text at the specified position.
-The position of the text to inspect.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to strikethrough.
A Boolean flag that indicates whether strikethrough is present at the position indicated by currentPosition.
Gets the application-defined drawing effect at the specified text position.
-The position of the text whose drawing effect is to be retrieved.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the drawing effect.
When this method returns, contains an address of a reference to the current application-defined drawing effect. Usually this effect is a foreground brush that is used in glyph drawing.
Gets the inline object at the specified position.
-The specified text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the inline object.
Contains the application-defined inline object.
Gets the typography setting of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the typography.
When this method returns, contains an address of a reference to the current typography setting.
Gets the length of the locale name of the text at the specified position.
-The position of the text to inspect.
Size of the character array, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Gets the locale name of the text at the specified position.
-The position of the text to inspect.
When this method returns, contains the character array receiving the current locale name.
Size of the character array, in character count, including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Draws text using the specified client drawing context.
-An application-defined drawing context.
Pointer to the set of callback functions used to draw parts of a text string.
The x-coordinate of the layout's left side.
The y-coordinate of the layout's top side.
If this method succeeds, it returns
To draw text with this method, a textLayout object needs to be created by the application using
After the textLayout object is obtained, the application calls the
Retrieves the information about each individual text line of the text string.
-When this method returns, contains a reference to an array of structures containing various calculated length values of individual text lines.
The maximum size of the lineMetrics array.
When this method returns, contains the actual size of the lineMetrics array that is needed.
If this method succeeds, it returns
If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Retrieves overall metrics for the formatted string.
-When this method returns, contains the measured distances of text and associated content after being formatted.
If this method succeeds, it returns
Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Overshoots of visible extents (in DIPs) outside the layout.
If this method succeeds, it returns
Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Retrieves logical properties and measurements of each glyph cluster.
-When this method returns, contains metrics, such as line-break or total advance width, for a glyph cluster.
The maximum size of the clusterMetrics array.
When this method returns, contains the actual size of the clusterMetrics array that is needed.
If this method succeeds, it returns
If maxClusterCount is not large enough, then E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
-Minimum width.
The application calls this function passing in a specific pixel location relative to the top-left location of the layout box and obtains the information about the correspondent hit-test metrics of the text string where the hit-test has occurred. When the specified pixel location is outside the text string, the function sets the output value *isInside to
The pixel location X to hit-test, relative to the top-left location of the layout box.
The pixel location Y to hit-test, relative to the top-left location of the layout box.
An output flag that indicates whether the hit-test location is at the leading or the trailing side of the character. When the output *isInside value is set to
An output flag that indicates whether the hit-test location is inside the text string. When
The output geometry fully enclosing the hit-test location. When the output *isInside value is set to
The application calls this function to get the pixel location relative to the top-left of the layout box given the text position and the logical side of the position. This function is normally used as part of caret positioning of text where the caret is drawn at the location corresponding to the current text editing position. It may also be used as a way to programmatically obtain the geometry of a particular text position in UI automation.
-The text position used to get the pixel location.
A Boolean flag that indicates whether the pixel location is of the leading or the trailing side of the specified text position.
When this method returns, contains the output pixel location X, relative to the top-left location of the layout box.
When this method returns, contains the output pixel location Y, relative to the top-left location of the layout box.
When this method returns, contains the output geometry fully enclosing the specified text position.
The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string. The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
The first text position of the specified range.
The number of positions of the specified range.
The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.
The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.
When this method returns, contains a reference to a buffer of the output geometry fully enclosing the specified position range. The buffer must be at least as large as maxHitTestMetricsCount.
Maximum number of boxes hitTestMetrics could hold in its buffer memory.
Actual number of geometries hitTestMetrics holds in its buffer memory.
If this method succeeds, it returns
Gets or sets the layout maximum width.
-Gets or sets the layout maximum height.
-Retrieves overall metrics for the formatted string.
-Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Specifies a range of text positions where format is applied in the text represented by an
Represents a set of application-defined callbacks that perform rendering of text, inline objects, and decorations such as underlines.
-Represents a bitmap that has been bound to an
To create a bitmap, use one of the following methods of the render target on which the bitmap will be drawn:
For information about the pixel formats supported by Direct2D bitmaps, see Supported Pixel Formats and Alpha Modes.
An
Returns the size, in device-independent pixels (DIPs), of the bitmap.
-The size, in DIPs, of the bitmap.
A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-The size, in pixels, of the bitmap.
Retrieves the pixel format and alpha mode of the bitmap.
-The pixel format and alpha mode of the bitmap.
Return the dots per inch (DPI) of the bitmap.
-The horizontal DPI of the image. You must allocate storage for this parameter.
The vertical DPI of the image. You must allocate storage for this parameter.
Copies the specified region from the specified bitmap into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The bitmap to copy from.
The area of bitmap to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Copies the specified region from the specified render target into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The render target that contains the region to copy.
The area of renderTarget to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
All clips and layers must be popped off of the render target before calling this method. The method returns
Copies the specified region from memory into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The data to copy.
The stride, or pitch, of the source bitmap stored in srcData. The stride is the byte count of a scanline (one row of pixels in memory). The stride can be computed from the following formula: pixel width * bytes per pixel + memory padding.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion; the two bitmap formats should match.
If this method is passed invalid input (such as an invalid destination rectangle), can produce unpredictable results, such as a distorted image or device failure.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Returns the size, in device-independent pixels (DIPs), of the bitmap.
-A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-Retrieves the pixel format and alpha mode of the bitmap.
-Paints an area with a bitmap.
-A bitmap brush is used to fill a geometry with a bitmap. Like all brushes, it defines an infinite plane of content. Because bitmaps are finite, the brush relies on an "extend mode" to determine how the plane is filled horizontally and vertically.
CreatingTo create a bitmap brush, use the
An
Defines an object that paints an area. Interfaces that derive from
An
Brush space in Direct2D is specified differently than in XPS and Windows Presentation Foundation (WPF). In Direct2D, brush space is not relative to the object being drawn, but rather is the current coordinate system of the render target, transformed by the brush transform, if present. To paint an object as it would be painted by a WPF brush, you must translate the brush space origin to the upper-left corner of the object's bounding box, and then scale the brush space so that the base tile fills the bounding box of the object.
For more information about brushes, see the Brushes Overview.
-Sets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Sets the transformation applied to the brush.
-The transformation to apply to this brush.
When you paint with a brush, it paints in the coordinate space of the render target. Brushes do not automatically position themselves to align with the object being painted; by default, they begin painting at the origin (0, 0) of the render target.
You can "move" the gradient defined by an
To align the content of an
The following illustrations show the effect of using an
The illustration on the right shows the result of transforming the
Gets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Gets the transform applied to this brush.
-The transform applied to this brush.
When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Gets or sets the degree of opacity of this brush.
-Gets or sets the transform applied to this brush.
-When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Specifies how the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies how the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies the interpolation mode used when the brush bitmap is scaled or rotated.
-The interpolation mode used when the brush bitmap is scaled or rotated.
This method sets the interpolation mode for a bitmap, which is an enum value that is specified in the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, bilinear interpolation positions the bitmap more precisely to the application requests, but blurs the bitmap in the process.
-Specifies the bitmap source that this brush uses to paint.
-The bitmap source used by the brush.
This method specifies the bitmap source that this brush uses to paint. The bitmap is not resized or rescaled automatically to fit the geometry that it fills. The bitmap stays at its native size. To resize or translate the bitmap, use the SetTransform method to apply a transform to the brush.
The native size of a bitmap is the width and height in bitmap pixels, divided by the bitmap DPI. This native size forms the base tile of the brush. To tile a subregion of the bitmap, you must generate a new bitmap containing this subregion and use SetBitmap to apply it to the brush. -
-Gets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Like all brushes,
Gets the method by which the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Like all brushes,
Gets the interpolation method used when the brush bitmap is scaled or rotated.
-The interpolation method used when the brush bitmap is scaled or rotated.
This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets the bitmap source that this brush uses to paint.
-When this method returns, contains the address to a reference to the bitmap with which this brush paints.
Gets or sets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the method by which the brush vertically tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the interpolation method used when the brush bitmap is scaled or rotated.
-This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets or sets the bitmap source that this brush uses to paint.
-Describes the pixel format and dpi of a bitmap.
-The bitmap's pixel format and alpha mode.
The horizontal dpi of the bitmap.
The vertical dpi of the bitmap.
Renders to an intermediate texture created by the CreateCompatibleRenderTarget method.
-An
To write directly to a WIC bitmap instead, use the
To create a bitmap render target, call the
Like other render targets, an
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-When this method returns, contains the address of a reference to the bitmap for this render target. This bitmap can be used for drawing operations.
If this method succeeds, it returns
The DPI for the
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-The DPI for the
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Adds an OpenType font feature.
-A structure that contains the OpenType name identifier and the execution parameter for the font feature being added.
If this method succeeds, it returns
Gets the number of OpenType font features for the current font.
-The number of font features for the current text format.
A single run of text can be associated with more than one typographic feature. The
Gets the font feature at the specified index.
-The zero-based index of the font feature to retrieve.
When this method returns, contains the font feature which is at the specified index.
A single run of text can be associated with more than one typographic feature. The
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Contains the center point, x-radius, and y-radius of an ellipse.
-The center point of the ellipse.
The X-radius of the ellipse.
The Y-radius of the ellipse.
Provides access to an device context that can accept GDI drawing commands.
-You don't create an
Not all render targets support the
Note that the QueryInterface method always succeeds; if the render target doesn't support the
To test whether a given render target supports the
Retrieves the device context associated with this render target.
-A value that specifies whether the device context should be cleared.
When this method returns, contains the device context associated with this render target. You must allocate storage for this parameter.
Calling this method flushes the render target.
This command can be called only after BeginDraw and before EndDraw. It should not be called between PushAxisAlignedClip/PopAxisAlignedClip commands or between PushLayer/PopLayer.
ReleaseDC must be called once for each call to GetDC.
-Indicates that drawing with the device context retrieved using the GetDC method is finished.
-If this method succeeds, it returns
ReleaseDC must be called once for each call to GetDC.
-Indicates the condition at the edges of inline object or text used to determine line-breaking behavior.
-Indicates whether a break is allowed by determining the condition of the neighboring text span or inline object.
Indicates that a line break is allowed, unless overruled by the condition of the neighboring text span or inline object, either prohibited by a "may not break" condition or forced by a "must break" condition.
Indicates that there should be no line break, unless overruled by a "must break" condition from the neighboring text span or inline object.
Indicates that the line break must happen, regardless of the condition of the adjacent text span or inline object.
Specifies the type of DirectWrite factory object.
-A DirectWrite factory object contains information about its internal state, such as font loader registration and cached font data. In most cases you should use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state information, thereby reducing memory usage. However, there are cases when it is desirable to reduce the impact of a component on the rest of the process, such as a plug-in from an untrusted source, by sandboxing and isolating it from the rest of the process components. In such cases, you should use an isolated factory for the sandboxed component.
-Indicates that the DirectWrite factory is a shared factory and that it allows for the reuse of cached font data across multiple in-process components. Such factories also take advantage of cross process font caching components for better performance.
Indicates that the DirectWrite factory object is isolated. Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
Indicates the direction of flow for placing lines of text in a paragraph.
-Specifies that text lines are placed from top to bottom.
Indicates the file format of a complete font face.
-Font formats that consist of multiple files, such as Type 1 .PFM and .PFB, have a single enum entry.
-OpenType font face with CFF outlines.
OpenType font face with TrueType outlines.
OpenType font face that is a part of a TrueType collection.
A Type 1 font face.
A vector .FON format font face.
A bitmap .FON format font face.
Font face type is not recognized by the DirectWrite font system.
A value that indicates the typographic feature of text supplied by the font.
-Replaces figures separated by a slash with an alternative form.
Equivalent OpenType tag: 'afrc'
Turns capital characters into petite capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in petite-cap form to avoid disrupting the flow of text. See the pcap feature description for notes on the relationship of caps, smallcaps and petite caps.
Equivalent OpenType tag: 'c2pc'
Turns capital characters into small capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in small-cap form to avoid disrupting the flow of text.
Equivalent OpenType tag: 'c2sc'
In specified situations, replaces default glyphs with alternate forms which provide better joining behavior. Used in script typefaces which are designed to have some or all of their glyphs join.
Equivalent OpenType tag: 'calt'
Shifts various punctuation marks up to a position that works better with all-capital sequences or sets of lining figures; also changes oldstyle figures to lining figures. By default, glyphs in a text face are designed to work with lowercase characters. Some characters should be shifted vertically to fit the higher visual center of all-capital or lining text. Also, lining figures are the same height (or close to it) as capitals, and fit much better with all-capital text.
Equivalent OpenType tag: 'case'
To minimize the number of glyph alternates, it is sometimes desired to decompose a character into two glyphs. Additionally, it may be preferable to compose two characters into a single glyph for better glyph processing. This feature permits such composition/decomposition. The feature should be processed as the first feature processed, and should be processed only when it is called.
Equivalent OpenType tag: 'ccmp'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. Unlike other ligature features, clig specifies the context in which the ligature is recommended. This capability is important in some script designs and for swash ligatures.
Equivalent OpenType tag: 'clig'
Globally adjusts inter-glyph spacing for all-capital text. Most typefaces contain capitals and lowercase characters, and the capitals are positioned to work with the lowercase. When capitals are used for words, they need more space between them for legibility and esthetics. This feature would not apply to monospaced designs. Of course the user may want to override this behavior in order to do more pronounced letterspacing for esthetic reasons.
Equivalent OpenType tag: 'cpsp'
Replaces default character glyphs with corresponding swash glyphs in a specified context. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'cswh'
In cursive scripts like Arabic, this feature cursively positions adjacent glyphs.
Equivalent OpenType tag: 'curs'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures which may be used for special effect, at the user's preference.
Equivalent OpenType tag: 'dlig'
Replaces standard forms in Japanese fonts with corresponding forms preferred by typographers. For example, a user would invoke this feature to replace kanji character U+5516 with U+555E. -
Equivalent OpenType tag: 'expt'
Replaces figures separated by a slash with 'common' (diagonal) fractions.
Equivalent OpenType tag: 'frac'
Replaces glyphs set on other widths with glyphs set on full (usually em) widths. In a CJKV font, this may include "lower ASCII" Latin characters and various symbols. In a European font, this feature replaces proportionally-spaced glyphs with monospaced glyphs, which are generally set on widths of 0.6 em. For example, a user may invoke this feature in a Japanese font to get full monospaced Latin glyphs instead of the corresponding proportionally-spaced versions.
Equivalent OpenType tag: 'fwid'
Produces the half forms of consonants in Indic scripts. For example, in Hindi (Devanagari script), the conjunct KKa, obtained by doubling the Ka, is denoted with a half form of Ka followed by the full form.
Equivalent OpenType tag: 'half'
Produces the halant forms of consonants in Indic scripts. For example, in Sanskrit (Devanagari script), syllable final consonants are frequently required in their halant form.
Equivalent OpenType tag: 'haln'
Respaces glyphs designed to be set on full-em widths, fitting them onto half-em widths. This differs from hwid in that it does not substitute new glyphs.
Equivalent OpenType tag: 'halt'
Replaces the default (current) forms with the historical alternates. While some ligatures are also used for historical effect, this feature deals only with single characters. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hist'
Replaces standard kana with forms that have been specially designed for only horizontal writing. This is a typographic optimization for improved fit and more even color.
Equivalent OpenType tag: 'hkna'
Replaces the default (current) forms with the historical alternates. Some ligatures were in common use in the past, but appear anachronistic today. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hlig'
Replaces glyphs on proportional widths, or fixed widths other than half an em, with glyphs on half-em (en) widths. Many CJKV fonts have glyphs which are set on multiple widths; this feature selects the half-em version. There are various contexts in which this is the preferred behavior, including compatibility with older desktop documents.
Equivalent OpenType tag: 'hwid'
Used to access the JIS X 0212-1990 glyphs for the cases when the JIS X 0213:2004 form is encoded. The JIS X 0212-1990 (aka, "Hojo Kanji") and JIS X 0213:2004 character sets overlap significantly. In some cases their prototypical glyphs differ. When building fonts that support both JIS X 0212-1990 and JIS X 0213:2004 (such as those supporting the Adobe-Japan 1-6 character collection), it is recommended that JIS X 0213:2004 forms be the preferred encoded form.
Equivalent OpenType tag: 'hojo'
The National Language Council (NLC) of Japan has defined new glyph shapes for a number of JIS characters, which were incorporated into JIS X 0213:2004 as new prototypical forms. The 'jp04' feature is A subset of the 'nlck' feature, and is used to access these prototypical glyphs in a manner that maintains the integrity of JIS X 0213:2004.
Equivalent OpenType tag: 'jp04'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS C 6226-1978 (JIS78) specification.
Equivalent OpenType tag: 'jp78'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS X 0208-1983 (JIS83) specification.
Equivalent OpenType tag: 'jp83'
Replaces Japanese glyphs from the JIS78 or JIS83 specifications with the corresponding forms from the JIS X 0208-1990 (JIS90) specification.
Equivalent OpenType tag: 'jp90'
Adjusts amount of space between glyphs, generally to provide optically consistent spacing between glyphs. Although a well-designed typeface has consistent inter-glyph spacing overall, some glyph combinations require adjustment for improved legibility. Besides standard adjustment in the horizontal direction, this feature can supply size-dependent kerning data via device tables, "cross-stream" kerning in the Y text direction, and adjustment of glyph placement independent of the advance adjustment. Note that this feature may apply to runs of more than two glyphs, and would not be used in monospaced fonts. Also note that this feature does not apply to text set vertically.
Equivalent OpenType tag: 'kern'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers the ligatures which the designer/manufacturer judges should be used in normal conditions.
Equivalent OpenType tag: 'liga'
Changes selected figures from oldstyle to the default lining form. For example, a user may invoke this feature in order to get lining figures, which fit better with all-capital text. This feature overrides results of the Oldstyle Figures feature (onum).
Equivalent OpenType tag: 'lnum'
Enables localized forms of glyphs to be substituted for default forms. Many scripts used to write multiple languages over wide geographical areas have developed localized variant forms of specific letters, which are used by individual literary communities. For example, a number of letters in the Bulgarian and Serbian alphabets have forms distinct from their Russian counterparts and from each other. In some cases the localized form differs only subtly from the script 'norm', in others the forms are radically distinct.
Equivalent OpenType tag: 'locl'
Positions mark glyphs with respect to base glyphs. For example, in Arabic script positioning the Hamza above the Yeh.
Equivalent OpenType tag: 'mark'
Replaces standard typographic forms of Greek glyphs with corresponding forms commonly used in mathematical notation (which are a subset of the Greek alphabet).
Equivalent OpenType tag: 'mgrk'
Positions marks with respect to other marks. Required in various non-Latin scripts like Arabic. For example, in Arabic, the ligaturised mark Ha with Hamza above it can also be obtained by positioning these marks relative to one another.
Equivalent OpenType tag: 'mkmk'
Replaces default glyphs with various notational forms (such as glyphs placed in open or solid circles, squares, parentheses, diamonds or rounded boxes). In some cases an annotation form may already be present, but the user may want a different one.
Equivalent OpenType tag: 'nalt'
Used to access glyphs made from glyph shapes defined by the National Language Council (NLC) of Japan for a number of JIS characters in 2000.
Equivalent OpenType tag: 'nlck'
Changes selected figures from the default lining style to oldstyle form. For example, a user may invoke this feature to get oldstyle figures, which fit better into the flow of normal upper- and lowercase text. This feature overrides results of the Lining Figures feature (lnum).
Equivalent OpenType tag: 'onum'
Replaces default alphabetic glyphs with the corresponding ordinal forms for use after figures. One exception to the follows-a-figure rule is the numero character (U+2116), which is actually a ligature substitution, but is best accessed through this feature.
Equivalent OpenType tag: 'ordn'
Respaces glyphs designed to be set on full-em widths, fitting them onto individual (more or less proportional) horizontal widths. This differs from pwid in that it does not substitute new glyphs (GPOS, not GSUB feature). The user may prefer the monospaced form, or may simply want to ensure that the glyph is well-fit and not rotated in vertical setting (Latin forms designed for proportional spacing would be rotated).
Equivalent OpenType tag: 'palt'
Turns lowercase characters into petite capitals. Forms related to petite capitals, such as specially designed figures, may be included. Some fonts contain an additional size of capital letters, shorter than the regular smallcaps and it is referred to as petite caps. Such forms are most likely to be found in designs with a small lowercase x-height, where they better harmonise with lowercase text than the taller smallcaps (for examples of petite caps, see the Emigre type families Mrs Eaves and Filosofia).
Equivalent OpenType tag: 'pcap'
Replaces figure glyphs set on uniform (tabular) widths with corresponding glyphs set on glyph-specific (proportional) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'pnum'
Replaces glyphs set on uniform widths (typically full or half-em) with proportionally spaced glyphs. The proportional variants are often used for the Latin characters in CJKV fonts, but may also be used for Kana in Japanese fonts.
Equivalent OpenType tag: 'pwid'
Replaces glyphs on other widths with glyphs set on widths of one quarter of an em (half an en). The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'qwid'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures, which the script determines as required to be used in normal conditions. This feature is important for some scripts to ensure correct glyph formation.
Equivalent OpenType tag: 'rlig'
Identifies glyphs in the font which have been designed for "ruby", from the old typesetting term for four-point-sized type. Japanese typesetting often uses smaller kana glyphs, generally in superscripted form, to clarify the meaning of kanji which may be unfamiliar to the reader.
Equivalent OpenType tag: 'ruby'
Replaces the default forms with the stylistic alternates. Many fonts contain alternate glyph designs for a purely esthetic effect; these don't always fit into a clear category like swash or historical. As in the case of swash glyphs, there may be more than one alternate form.
Equivalent OpenType tag: 'salt'
Replaces lining or oldstyle figures with inferior figures (smaller glyphs which sit lower than the standard baseline, primarily for chemical or mathematical notation). May also replace lowercase characters with alphabetic inferiors.
Equivalent OpenType tag: 'sinf'
Turns lowercase characters into small capitals. This corresponds to the common SC font layout. It is generally used for display lines set in Large & small caps, such as titles. Forms related to small capitals, such as oldstyle figures, may be included.
Equivalent OpenType tag: 'smcp'
Replaces 'traditional' Chinese or Japanese forms with the corresponding 'simplified' forms.
Equivalent OpenType tag: 'smpl'
In addition to, or instead of, stylistic alternatives of individual glyphs (see 'salt' feature), some fonts may contain sets of stylistic variant glyphs corresponding to portions of the character set, such as multiple variants for lowercase letters in a Latin font. Glyphs in stylistic sets may be designed to harmonise visually, interract in particular ways, or otherwise work together. Examples of fonts including stylistic sets are Zapfino Linotype and Adobe's Poetica. Individual features numbered sequentially with the tag name convention 'ss01' 'ss02' 'ss03' . 'ss20' provide a mechanism for glyphs in these sets to be associated via GSUB lookup indexes to default forms and to each other, and for users to select from available stylistic sets
Equivalent OpenType tag: 'ss01'
See the description for
Equivalent OpenType tag: 'ss02'
See the description for
Equivalent OpenType tag: 'ss03'
See the description for
Equivalent OpenType tag: 'ss04'
See the description for
Equivalent OpenType tag: 'ss05'
See the description for
Equivalent OpenType tag: 'ss06'
See the description for
Equivalent OpenType tag: 'ss07'
See the description for
Equivalent OpenType tag: 'ss08'
See the description for
Equivalent OpenType tag: 'ss09'
See the description for
Equivalent OpenType tag: 'ss10'
See the description for
Equivalent OpenType tag: 'ss11'
See the description for
Equivalent OpenType tag: 'ss12'
See the description for
Equivalent OpenType tag: 'ss13'
See the description for
Equivalent OpenType tag: 'ss14'
See the description for
Equivalent OpenType tag: 'ss15'
See the description for
Equivalent OpenType tag: 'ss16'
See the description for
Equivalent OpenType tag: 'ss17'
See the description for
Equivalent OpenType tag: 'ss18'
See the description for
Equivalent OpenType tag: 'ss19'
See the description for
Equivalent OpenType tag: 'ss20'
May replace a default glyph with a subscript glyph, or it may combine a glyph substitution with positioning adjustments for proper placement.
Equivalent OpenType tag: 'subs'
Replaces lining or oldstyle figures with superior figures (primarily for footnote indication), and replaces lowercase letters with superior letters (primarily for abbreviated French titles).
Equivalent OpenType tag: 'sups'
Replaces default character glyphs with corresponding swash glyphs. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'swsh'
Replaces the default glyphs with corresponding forms designed specifically for titling. These may be all-capital and/or larger on the body, and adjusted for viewing at larger sizes.
Equivalent OpenType tag: 'titl'
Replaces 'simplified' Japanese kanji forms with the corresponding 'traditional' forms. This is equivalent to the Traditional Forms feature, but explicitly limited to the traditional forms considered proper for use in personal names (as many as 205 glyphs in some fonts).
Equivalent OpenType tag: 'tnam'
Replaces figure glyphs set on proportional widths with corresponding glyphs set on uniform (tabular) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'tnum'
Replaces 'simplified' Chinese hanzi or Japanese kanji forms with the corresponding 'traditional' forms.
Equivalent OpenType tag: 'trad'
Replaces glyphs on other widths with glyphs set on widths of one third of an em. The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'twid'
Maps upper- and lowercase letters to a mixed set of lowercase and small capital forms, resulting in a single case alphabet (for an example of unicase, see the Emigre type family Filosofia). The letters substituted may vary from font to font, as appropriate to the design. If aligning to the x-height, smallcap glyphs may be substituted, or specially designed unicase forms might be used. Substitutions might also include specially designed figures. -
Equivalent OpenType tag: 'unic'
Allows the user to change from the default 0 to a slashed form. Some fonts contain both a default form of zero, and an alternative form which uses a diagonal slash through the counter. Especially in condensed designs, it can be difficult to distinguish between 0 and O (zero and capital O) in any situation where capitals and lining figures may be arbitrarily mixed.
Equivalent OpenType tag: 'zero'
The type of a font represented by a single font file. Font formats that consist of multiple files, for example Type 1 .PFM and .PFB, have separate enum values for each of the file types.
-Font type is not recognized by the DirectWrite font system.
OpenType font with CFF outlines.
OpenType font with TrueType outlines.
OpenType font that contains a TrueType collection.
Type 1 PFM font.
Type 1 PFB font.
Vector .FON font.
Bitmap .FON font.
Specifies algorithmic style simulations to be applied to the font face. Bold and oblique simulations can be combined via bitwise OR operation.
-Style simulations are not recommended for good typographic quality.
-Indicates that no simulations are applied to the font face.
Indicates that algorithmic emboldening is applied to the font face.
Indicates that algorithmic italicization is applied to the font face.
Represents the degree to which a font has been stretched compared to a font's normal aspect ratio. The enumerated values correspond to the usWidthClass definition in the OpenType specification. The usWidthClass represents an integer value between 1 and 9?lower values indicate narrower widths; higher values indicate wider widths.
-A font stretch describes the degree to which a font form is stretched from its normal aspect ratio, which is the original width to height ratio specified for the glyphs in the font. - The following illustration shows an example of Normal and Condensed stretches for the Rockwell Bold typeface.
Note??Values other than the ones defined in the enumeration are considered to be invalid, and are rejected by font API functions.
-Predefined font stretch : Not known (0).
Predefined font stretch : Ultra-condensed (1).
Predefined font stretch : Extra-condensed (2).
Predefined font stretch : Condensed (3).
Predefined font stretch : Semi-condensed (4).
Predefined font stretch : Normal (5).
Predefined font stretch : Medium (5).
Predefined font stretch : Semi-expanded (6).
Predefined font stretch : Expanded (7).
Predefined font stretch : Extra-expanded (8).
Predefined font stretch : Ultra-expanded (9).
Represents the style of a font face as normal, italic, or oblique.
-Three terms categorize the slant of a font: normal, italic, and oblique.
| Font style | Description |
|---|---|
| Normal | The characters in a normal, or roman, font are upright. - |
| Italic - | The characters in an italic font are truly slanted and appear as they were designed. - |
| Oblique | The characters in an oblique font are artificially slanted. |
?
For Oblique, the slant is achieved by performing a shear transformation on the characters from a normal font. When a true italic font is not available on a computer or printer, an oblique style can be generated from the normal font and used to simulate an italic font. The following illustration shows the normal, italic, and oblique font styles for the Palatino Linotype font. Notice how the italic font style has a more flowing and visually appealing appearance than the oblique font style, which is simply created by skewing the normal font style version of the text.
Note?? Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
-Font style : Normal.
Font style : Oblique.
Font style : Italic.
Represents the density of a typeface, in terms of the lightness or heaviness of the strokes. The enumerated values correspond to the usWeightClass definition in the OpenType specification. The usWeightClass represents an integer value between 1 and 999. Lower values indicate lighter weights; higher values indicate heavier weights.
-Weight differences are generally differentiated by an increased stroke or thickness that is associated with a given character in a typeface, as compared to a "normal" character from that same typeface. - The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
Note??Not all weights are available for all typefaces. When a weight is not available for a typeface, the closest matching weight is returned.
Font weight values less than 1 or greater than 999 are considered invalid, and they are rejected by font API functions.
-Predefined font weight : Thin (100).
Predefined font weight : Extra-light (200).
Predefined font weight : Ultra-light (200).
Predefined font weight : Light (300).
Predefined font weight : Normal (400).
Predefined font weight : Regular (400).
Predefined font weight : Medium (500).
Predefined font weight : Demi-bold (600).
Predefined font weight : Semi-bold (600).
Predefined font weight : Bold (700).
Predefined font weight : Extra-bold (800).
Predefined font weight : Ultra-bold (800).
Predefined font weight : Black (900).
Predefined font weight : Heavy (900).
Predefined font weight : Extra-black (950).
Predefined font weight : Ultra-black (950).
The informational string enumeration which identifies a string embedded in a font file.
-Indicates the string containing the unspecified name ID.
Indicates the string containing the copyright notice provided by the font.
Indicates the string containing a version number.
Indicates the string containing the trademark information provided by the font.
Indicates the string containing the name of the font manufacturer.
Indicates the string containing the name of the font designer.
Indicates the string containing the URL of the font designer (with protocol, e.g., http://, ftp://).
Indicates the string containing the description of the font. This may also contain revision information, usage recommendations, history, features, etc.
Indicates the string containing the URL of the font vendor (with protocol, e.g., http://, ftp://). If a unique serial number is embedded in the URL, it can be used to register the font.
Indicates the string containing the description of how the font may be legally used, or different example scenarios for licensed use.
Indicates the string containing the URL where additional licensing information can be found.
Indicates the string containing the GDI-compatible family name. Since GDI allows a maximum of four fonts per family, fonts in the same family may have different GDI-compatible family names (e.g., "Arial", "Arial Narrow", "Arial Black").
Indicates the string containing a GDI-compatible subfamily name.
Indicates the string containing the family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI. This name is typically only present if it differs from the GDI-compatible family name.
Indicates the string containing the subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
Contains sample text for display in font lists. This can be the font name or any other text that the designer thinks is the best example to display the font in.
The method used for line spacing in a text layout.
-The line spacing method is set by using the SetLineSpacing method of the
Line spacing depends solely on the content, adjusting to accommodate the size of fonts and inline objects.
Lines are explicitly set to uniform spacing, regardless of the size of fonts and inline objects. This can be useful to avoid the uneven appearance that can occur from font fallback.
Specifies how to apply number substitution on digits and related punctuation.
-Specifies that the substitution method should be determined based on the LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
If the culture is Arabic or Persian, specifies that the number shapes depend on the context. Either traditional or nominal number shapes are used, depending on the nearest preceding strong character or (if there is none) the reading direction of the paragraph.
Specifies that code points 0x30-0x39 are always rendered as nominal numeral shapes (ones of the European number), that is, no substitution is performed.
Specifies that numbers are rendered using the national number shapes as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
Specifies that numbers are rendered using the traditional shapes for the specified culture. For most cultures, this is the same as NativeNational. However, NativeNational results in Latin numbers for some Arabic cultures, whereasDWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL results in arabic numbers for all Arabic cultures.
Specifies the alignment of paragraph text along the flow direction axis, relative to the top and bottom of the flow's layout box.
-The top of the text flow is aligned to the top edge of the layout box.
The bottom of the text flow is aligned to the bottom edge of the layout box.
The center of the flow is aligned to the center of the layout box.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text. -
-The red, green, and blue color components of each pixel are assumed to occupy the same point.
Each pixel is composed of three vertical stripes, with red on the left, green in the center, and blue on the right. This is the most common pixel geometry for LCD monitors.
Each pixel is composed of three vertical stripes, with blue on the left, green in the center, and red on the right.
Specifies the direction in which reading progresses.
-Indicates that reading progresses from left to right.
Indicates that reading progresses from right to left.
Represents a method of rendering glyphs.
-Specifies that the rendering mode is determined automatically, based on the font and size.
Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground color of the text or retains the color of the background.
Specifies ClearType rendering with the same metrics as bi-level text. Glyphs can only be positioned on whole-pixel boundaries.
Specifies ClearType rendering with the same metrics as text rendering using GDI using a font created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than with bi-level text, but glyphs are still positioned on whole-pixel boundaries.
Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is typically used with small to medium font sizes (up to 16 ppem).
Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions. This is typically used at larger sizes to makes curves and diagonal lines look smoother, at the expense of some softness.
Specifies that rendering should bypass the rasterizer and use the outlines directly. This is typically used at very large sizes.
Indicates additional shaping requirements for text.
-Indicates that there is no additional shaping requirements for text. Text is shaped with the writing system default behavior.
Indicates that text should leave no visible control or format control characters.
Specifies the alignment of paragraph text along the reading direction axis, relative to the leading and trailing edge of the layout box.
-The leading edge of the paragraph text is aligned to the leading edge of the layout box.
The trailing edge of the paragraph text is aligned to the trailing edge of the layout box.
The center of the paragraph text is aligned to the center of the layout box.
Identifies a type of alpha texture.
-An alpha texture is a bitmap of alpha values, each representing opacity of a pixel or subpixel.
-Specifies an alpha texture for aliased text rendering (that is, each pixel is either fully opaque or fully transparent), with one byte per pixel.
Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and one byte per pixel in the vertical dimension.
Specifies the text granularity used to trim text overflowing the layout box.
-No trimming occurs. Text flows beyond the layout width.
Trimming occurs at a character cluster boundary.
Trimming occurs at a word boundary.
Specifies the word wrapping to be used in a particular multiline paragraph.
-Indicates that words are broken across lines to avoid text overflowing the layout box.
Indicates that words are kept within the same line even when it overflows the layout box. This option is often used with scrolling to reveal overflow text.
Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
-A value that specifies whether the factory object will be shared or isolated.
A
An address of a reference to the newly created DirectWrite factory object.
If this function succeeds, it returns
This function creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects. DirectWrite factory contains internal state data such as font loader registration and cached font data. In most cases it is recommended you use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state data, and thereby reduce memory usage. However, there are cases when it is desirable to reduce the impact of a component, such as a plug-in from an untrusted source, on the rest of the process, by sandboxing and isolating it from the rest of the process components. In such cases, it is recommended you use an isolated factory for the sandboxed component.
The following example shows how to create a shared DirectWrite factory.
if (SUCCEEDED(hr))
- { hr = Represents a physical font in a font collection. This interface is used to create font faces from physical fonts, or to retrieve information such as font face metrics or face names from existing font faces.
-Gets the font family to which the specified font belongs.
-When this method returns, contains an address of a reference to the font family object to which the specified font belongs.
If this method succeeds, it returns
Gets the weight, or stroke thickness, of the specified font.
-A value that indicates the weight for the specified font.
Gets the stretch, or width, of the specified font.
-A value that indicates the type of stretch, or width, applied to the specified font.
Gets the style, or slope, of the specified font.
-A value that indicates the type of style, or slope, of the specified font.
Determines whether the font is a symbol font.
-TRUE if the font is a symbol font; otherwise,
Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-When this method returns, contains an address to a reference to the newly created localized strings object.
If this method succeeds, it returns
Gets a localized strings collection containing the specified informational strings, indexed by locale name.
-A value that identifies the informational string to get. For example,
When this method returns, contains an address of a reference to the newly created localized strings object.
When this method returns, TRUE if the font contains the specified string ID; otherwise,
If the font does not contain the string specified by informationalStringID, the return value is
Gets a value that indicates what simulations are applied to the specified font.
-A value that indicates one or more of the types of simulations (none, bold, or oblique) applied to the specified font.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, contains a structure that has font metrics for the current font face. The metrics returned by this function are in font design units.
Determines whether the font supports a specified character.
-A Unicode (UCS-4) character value for the method to inspect.
When this method returns, TRUE if the font supports the specified character; otherwise,
Creates a font face object for the font.
-When this method returns, contains an address of a reference to the newly created font face object.
If this method succeeds, it returns
Gets the font family to which the specified font belongs.
-Gets the weight, or stroke thickness, of the specified font.
-Gets the stretch, or width, of the specified font.
-Gets the style, or slope, of the specified font.
-Determines whether the font is a symbol font.
-Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-Gets a value that indicates what simulations are applied to the specified font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Represents a family of related fonts.
-A font family is a set of fonts that share the same family name, such as "Times New Roman", but that differ in features. These feature differences include style, such as italic, and weight, such as bold. The following illustration shows examples of fonts that are members of the "Times New Roman" font family.
An
null ; // Get the font family.
- if (SUCCEEDED(hr))
- { hr = pFontCollection->GetFontFamily(i, &pFontFamily);
- }
- The font family name is used to specify the font family for text layout and text format objects. You can get a list of localized font family names from an
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- }
- Represents a list of fonts.
-Gets the font collection that contains the fonts in the font list.
-When this method returns, contains the address of a reference to the current
If this method succeeds, it returns
Gets the number of fonts in the font list.
-The number of fonts in the font list.
Gets a font given its zero-based index.
-Zero-based index of the font in the font list.
When this method returns, contains the address of a reference to the newly created
Gets the font collection that contains the fonts in the font list.
-Gets the number of fonts in the font list.
-Creates a localized strings object that contains the family names for the font family, indexed by locale name.
-The address of a reference to the newly created
If this method succeeds, it returns
The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the font that best matches the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
When this method returns, contains the address of a reference to the newly created
Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
An address of a reference to the newly created
Creates a localized strings object that contains the family names for the font family, indexed by locale name.
- The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- A built-in implementation of the
Obtains the length of the absolute file path from the font file reference key.
-Font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
Size of font file reference key in bytes.
Length of the file path string, not including the terminated
Obtains the absolute font file path from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The character array that receives the local file path.
The length of the file path character array.
If this method succeeds, it returns
Obtains the last write time of the file from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The time of the last font file modification.
Contains information about a glyph cluster.
-The total advance width of all glyphs in the cluster.
The number of text positions in the cluster.
Indicates whether a line can be broken right after the cluster.
Indicates whether the cluster corresponds to a whitespace character.
Indicates whether the cluster corresponds to a newline character.
Indicates whether the cluster corresponds to a soft hyphen character.
Indicates whether the cluster is read from right to left.
Reserved for future use.
The
The number of font design units per em unit. Font files use their own coordinate system of font design units. A font design unit is the smallest measurable unit in the em square, an imaginary square that is used to size and align glyphs. The concept of em square is used as a reference scale factor when defining font size and device transformation semantics. The size of one em square is also commonly used to compute the paragraph identation value.
The ascent value of the font face in font design units. Ascent is the distance from the top of font character alignment box to the English baseline.
The descent value of the font face in font design units. Descent is the distance from the bottom of font character alignment box to the English baseline.
The line gap in font design units. Recommended additional white space to add between lines to improve legibility. The recommended line spacing (baseline-to-baseline distance) is the sum of ascent, descent, and lineGap. The line gap is usually positive or zero but can be negative, in which case the recommended line spacing is less than the height of the character alignment box.
The cap height value of the font face in font design units. Cap height is the distance from the English baseline to the top of a typical English capital. Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
The x-height value of the font face in font design units. x-height is the distance from the English baseline to the top of lowercase letter "x", or a similar lowercase character.
The underline position value of the font face in font design units. Underline position is the position of underline relative to the English baseline. The value is usually made negative in order to place the underline below the baseline.
The suggested underline thickness value of the font face in font design units.
The strikethrough position value of the font face in font design units. Strikethrough position is the position of strikethrough relative to the English baseline. The value is usually made positive in order to place the strikethrough above the baseline.
The suggested strikethrough thickness value of the font face in font design units.
Specifies the metrics of an individual glyph. The units depend on how the metrics are obtained.
-Specifies the X offset from the glyph origin to the left edge of the black box. The glyph origin is the current horizontal writing position. A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally. The value is negative when the right edge of the black box overhangs the layout box.
Specifies the vertical offset from the vertical origin to the top of the black box. Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically. Note that the term "origin" by itself denotes the horizontal origin. The vertical origin is different. Its Y coordinate is specified by verticalOriginY value, and its X coordinate is half the advanceWidth to the right of the horizontal origin.
Specifies the vertical distance from the bottom edge of the black box to the advance height. This is positive when the bottom edge of the black box is within the layout box, or negative when the bottom edge of black box overhangs the layout box.
Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system. The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing and the top (that is, yMax) of the glyph's bounding box.
The optional adjustment to a glyph's position.
-An glyph offset changes the position of a glyph without affecting the pen position. Offsets are in logical, pre-transform units.
-The offset in the advance direction of the run. A positive advance offset moves the glyph to the right (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
The offset in the ascent direction, that is, the direction ascenders point. A positive ascender offset moves the glyph up (in pre-transform coordinates). A negative ascender offset moves the glyph down.
Describes the region obtained by a hit test.
-The first text position within the hit region.
The number of text positions within the hit region.
The x-coordinate of the upper-left corner of the hit region.
The y-coordinate of the upper-left corner of the hit region.
The width of the hit region.
The height of the hit region.
The BIDI level of the text positions within the hit region.
true if the hit region contains text; otherwise, false.
Contains properties describing the geometric measurement of an - application-defined inline object.
-The width of the inline object.
The height of the inline object.
The distance from the top of the object to the point where it is lined up with the adjacent text. If the baseline is at the bottom, then baseline simply equals height.
A Boolean flag that indicates whether the object is to be placed upright or alongside the text baseline for vertical text.
Contains information about a formatted line of text.
-The number of text positions in the text line. This includes any trailing whitespace and newline characters.
The number of whitespace positions at the end of the text line. Newline sequences are considered whitespace.
The number of characters in the newline sequence at the end of the text line. If the count is zero, then the text line was either wrapped or it is the end of the text.
The height of the text line.
The distance from the top of the text line to its baseline.
The line is trimmed.
Indicates how much any visible DIPs (device independent pixels) overshoot each side of the layout or inline objects.
Positive overhangs indicate that the visible area extends outside the layout box or inline object, while negative values mean there is whitespace inside. The returned values are unaffected by rendering transforms or pixel snapping. Additionally, they may not exactly match the final target's pixel bounds after applying grid fitting and hinting.
-The distance from the left-most visible DIP to its left-alignment edge.
The distance from the top-most visible DIP to its top alignment edge.
The distance from the right-most visible DIP to its right-alignment edge.
The distance from the bottom-most visible DIP to its lower-alignment edge.
Stores the association of text and its writing system script, as well as some display attributes.
-The zero-based index representation of writing system script.
A value that indicates additional shaping requirement of text.
Shaping output properties for an output glyph.
-Indicates that the glyph is shaped alone.
Reserved for future use.
Contains information regarding the size and placement of strikethroughs. All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the strikethrough, measured parallel to the baseline.
A value that indicates the thickness of the strikethrough, measured perpendicular to the baseline.
A value that indicates the offset of the strikethrough from the baseline. A positive offset represents a position below the baseline and a negative offset is above. Typically, the offset will be negative.
Reading direction of the text associated with the strikethrough. This value is used to interpret whether the width value runs horizontally or vertically.
Flow direction of the text associated with the strikethrough. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters containing the locale of the text that is the strikethrough is being drawn over.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Contains the metrics associated with text after layout. All coordinates are in device independent pixels (DIPs).
-A value that indicates the left-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the top-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the width of the formatted text, while ignoring trailing whitespace at the end of each line.
The width of the formatted text, taking into account the trailing whitespace at the end of each line.
The height of the formatted text. The height of an empty string is set to the same value as that of the default font.
The initial width given to the layout. It can be either larger or smaller than the text content width, depending on whether the text was wrapped.
Initial height given to the layout. Depending on the length of the text, it may be larger or smaller than the text content height.
The maximum reordering count of any line of text, used to calculate the most number of hit-testing boxes needed. If the layout has no bidirectional text, or no text at all, the minimum level is 1.
Specifies the trimming option for text overflowing the layout box.
-A value that specifies the text granularity used to trim text overflowing the layout box.
A character code used as the delimiter that signals the beginning of the portion of text to be preserved. Most useful for path ellipsis, where the delimiter would be a slash.
A value that indicates how many occurrences of the delimiter to step back.
Contains a set of typographic features to be applied during text shaping.
-A reference to a structure that specifies properties used to identify and execute typographic features in the font.
A value that indicates the number of features being applied to a font face.
Contains information about the width, thickness, offset, run height, reading direction, and flow direction of an underline.
-All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the underline, measured parallel to the baseline.
A value that indicates the thickness of the underline, measured perpendicular to the baseline.
A value that indicates the offset of the underline from the baseline. A positive offset represents a position below the baseline (away from the text) and a negative offset is above (toward the text).
A value that indicates the height of the tallest run where the underline is applied.
A value that indicates the reading direction of the text associated with the underline. This value is used to interpret whether the width value runs horizontally or vertically.
A value that indicates the flow direction of the text associated with the underline. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters which contains the locale of the text that the underline is being drawn under. For example, in vertical text, the underline belongs on the left for Chinese but on the right for Japanese.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Specifies how the alpha value of a bitmap or render target should be treated.
-The
When describing an RGBA color using straight alpha, the alpha value of the color is stored in the alpha channel. For example, to describe a red color that is 60% opaque, you'd use the following values: (255, 0, 0, 255 * 0.6) = (255, 0, 0, 153). The 255 value indicates full red, and 153 (which is 60 percent of 255) indicates that the color should have an opacity of 60 percent.
When describing an RGBA color using premultiplied alpha, each color is multiplied by the alpha value: (255 * 0.6, 0 * 0.6, 0 * 0.6, 255 * 0.6) = (153, 0, 0, 153).
Regardless of the alpha mode of the render target, D2D1_COLOR_F values are always interpreted as straight alpha. For example, when specifying the color of an
Regardless of the alpha mode setting, a render target's contents support transparency. For example, if you draw a partially transparent red rectangle with a render target with an alpha mode of
If you draw a partially transparent red rectangle when the alpha mode is
If you specify an alpha mode other than
You can use the SetTextAntialiasMode method to change the text antialias mode back to
The alpha value might not be meaningful.
The alpha value has been premultiplied. Each color is first scaled by the alpha value. The alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. If a color channel value in a premultiplied format is greater than the alpha channel, the standard source-over blending math results in an additive blend.
The alpha value has not been premultiplied. The alpha channel indicates the transparency of the color.
The alpha value is ignored.
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Specifies whether an arc should be greater than 180 degrees.
-An arc's sweep should be 180 degrees or less.
An arc's sweep should be 180 degrees or greater.
Specifies the algorithm that is used when images are scaled or rotated.
- To stretch an image, each pixel in the original image must be mapped to a group of pixels in the larger image. To shrink an image, groups of pixels in the original image must be mapped to single pixels in the smaller image. The effectiveness of the algorithms that perform these mappings determines the quality of a scaled image. Algorithms that produce higher-quality scaled images tend to require more processing time.
Use the exact color of the nearest bitmap pixel to the current rendering pixel.
Interpolate a color from the four bitmap pixels that are the nearest to the rendering pixel.
Describes the shape at the end of a line or segment.
-The following illustration shows the available cap styles for lines or segments. The red portion of the line shows the extra area added by the line cap setting.
-A cap that does not extend past the last point of the line. Comparable to cap used for objects other than lines.
Half of a square that has a length equal to the line thickness.
A semicircle that has a diameter equal to the line thickness.
An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line.
Specifies the different methods by which two geometries can be combined.
-The following illustration shows the different geometry combine modes. -
-The two regions are combined by taking the union of both. Given two geometries, A and B, the resulting geometry is geometry A + geometry B.
The two regions are combined by taking their intersection. The new area consists of the overlapping region between the two geometries.
The two regions are combined by taking the area that exists in the first region but not the second and the area that exists in the second region but not the first. Given two geometries, A and B, the new region consists of (A-B) + (B-A).
The second region is excluded from the first. Given two geometries, A and B, the area of geometry B is removed from the area of geometry A, producing a region that is A-B.
Specifies additional features supportable by a compatible render target when it is created. This enumeration allows a bitwise combination of its member values.
-Use this enumeration when creating a compatible render target with the CreateCompatibleRenderTarget method. For more information about compatible render targets, see the Render Targets Overview.
The
The render target supports no additional features.
The render target supports interoperability with the Windows Graphics Device Interface (GDI).
Describes the sequence of dashes and gaps in a stroke.
-The following illustration shows several available dash styles. For more information, see the Stroke Style Example.
-A solid line with no breaks.
A dash followed by a gap of equal length. The dash and the gap are each twice as long as the stroke thickness.
The equivalent dash array for
A dot followed by a longer gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap, followed by another dot, followed by another gap.
The equivalent dash array for
The dash pattern is specified by an array of floating-point values.
Indicates the type of information provided by the Direct2D Debug Layer.
-To receive debugging messages, you must install the Direct2D Debug Layer.
-Specifies how a device context is initialized for GDI rendering when it is retrieved from the render target.
-Use this enumeration with the
The current contents of the render target are copied to the device context when it is initialized.
The device context is cleared to transparent black when it is initialized.
Specifies whether text snapping is suppressed or clipping to the layout rectangle is enabled. This enumeration allows a bitwise combination of its member values.
-Text is not vertically snapped to pixel boundaries. This setting is recommended for text that is being animated.
Text is clipped to the layout rectangle.
Text is vertically snapped to pixel boundaries and is not clipped to the layout rectangle.
Specifies how a brush paints areas outside of its normal content area.
-For an
For an example, see the Draw Extend Mode Example.
-Repeat the edge pixels of the brush's content for all regions outside the normal content area.
Repeat the brush's content.
The same as
Specifies whether Direct2D provides synchronization for an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread, and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU; however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Describes the minimum DirectX support required for hardware rendering by a render target.
-Direct2D determines whether the video card provides adequate hardware rendering support.
The video card must support DirectX 9.
The video card must support DirectX 10.
Indicates whether a specific
Indicates whether a specific
Specifies how the intersecting areas of geometries or figures are combined to form the area of the composite geometry.
-Use the
Direct2D fills the interior of a path by using one of the two fill modes specified by this enumeration:
To see the difference between the winding and alternate fill modes, assume that you have four circles with the same center and a different radius, as shown in the following illustration. The first one has the radius of 25, the second 50, the third 75, and the fourth 100.
The following illustration shows the shape filled by using the alternate fill mode. Notice that the center and third ring are not filled. This is because a ray drawn from any point in either of those two rings passes through an even number of segments.
The following illustration explains this process.
The following illustration shows how the same shape is filled when the winding fill mode is specified.
Notice that all the rings are filled. This is because all the segments run in the same direction, so a ray drawn from any point will cross one or more segments, and the sum of the crossings will not equal zero.
The following illustration explains this process. The red arrows represent the direction in which the segments are drawn and the black arrow represents an arbitrary ray that runs from a point in the innermost ring. Starting with a value of zero, for each segment that the ray crosses, a value of one is added for every clockwise intersection. All points lie in the fill region in this illustration, because the count does not equal zero.
-Determines whether a point is in the fill region by drawing a ray from that point to infinity in any direction, and then counting the number of path segments within the given shape that the ray crosses. If this number is odd, the point is in the fill region; if even, the point is outside the fill region.
Determines whether a point is in the fill region of the path by drawing a ray from that point to infinity in any direction, and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left, as long as left and right are seen from the perspective of the ray. After counting the crossings, if the result is zero, then the point is outside the path. Otherwise, it is inside the path.
Specifies which gamma is used for interpolation.
-Interpolating in a linear gamma space (
The first gradient is interpolated linearly in the space of the render target (sRGB in this case), and one can see the dark bands between each color. The second gradient uses a gamma-correct linear interpolation, and thus does not exhibit the same variations in brightness.
-Interpolation is performed in the standard RGB (sRGB) gamma.
Interpolation is performed in the linear-gamma color space.
Describes how one geometry object is spatially related to another geometry object.
-The relationship between the two geometries cannot be determined. This value is never returned by any D2D method.
The two geometries do not intersect at all.
The instance geometry is entirely contained by the passed-in geometry.
The instance geometry entirely contains the passed-in geometry.
The two geometries overlap but neither completely contains the other.
Specifies how a geometry is simplified to an
Specifies options that can be applied when a layer resource is applied to create a layer.
-ClearType antialiasing must use the current contents of the render target to blend properly. When a pushed layer requests initializing for ClearType, Direct 2D copies the current contents of the render target into the layer so that ClearType antialiasing can be performed. Rendering ClearType text into a transparent layer does not produce the desired results.
A small performance hit from re-copying content occurs when
The text in this layer does not use ClearType antialiasing.
The layer renders correctly for ClearType text. If the render target is set to ClearType, the layer continues to render ClearType. If the render target is set to ClearType and this option is not specified, the render target will be set to render gray-scale until the layer is popped. The caller can override this default by calling SetTextAntialiasMode while within the layer. This flag is slightly slower than the default.
Describes the shape that joins two lines or segments.
- A miter limit affects how sharp miter joins are allowed to be. If the line join style is
The following illustration shows different line join settings for the same stroked path geometry. For more information, see Stroke Style Example.
-Regular angular vertices.
Beveled vertices.
Rounded vertices.
Regular angular vertices unless the join would extend beyond the miter limit; otherwise, beveled vertices.
Indicates the measuring method used for text layout.
-Specifies that text is measured using glyph ideal metrics whose values are independent to the current display resolution.
Specifies that text is measured using glyph display-compatible metrics whose values tuned for the current display resolution.
Specifies that text is measured using the same glyph display metrics as text measured by GDI using a font created with CLEARTYPE_NATURAL_QUALITY.
Describes whether an opacity mask contains graphics or text. Direct2D uses this information to determine which gamma space to use when blending the opacity mask.
-The opacity mask contains graphics. The opacity mask is blended in the gamma 2.2 color space.
The opacity mask contains non-GDI text. The gamma space used for blending is obtained from the render target's text rendering parameters. (
The opacity mask contains text rendered using the GDI-compatible rendering mode. The opacity mask is blended using the gamma for GDI rendering.
Indicates whether a segment should be stroked and whether the join between this segment and the previous one should be smooth. This enumeration allows a bitwise combination of its member values.
-The segment is joined as specified by the
The segment is not stroked.
The segment is always joined with the one preceding it using a round line join, regardless of which
Describes how a render target behaves when it presents its content. This enumeration allows a bitwise combination of its member values.
-The render target waits until the display refreshes to present and discards the frame upon presenting.
The render target does not discard the frame upon presenting.
The render target does not wait until the display refreshes to present.
Describes whether a render target uses hardware or software rendering, or if Direct2D should select the rendering mode.
-Not every render target supports hardware rendering. For more information, see the Render Targets Overview.
-The render target uses hardware rendering, if available; otherwise, it uses software rendering.
The render target uses software rendering only.
The render target uses hardware rendering only.
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
Defines the direction that an elliptical arc is drawn.
-Arcs are drawn in a counterclockwise (negative-angle) direction.
Arcs are drawn in a clockwise (positive-angle) direction.
Describes the antialiasing mode used for drawing text.
-This enumeration is used with the SetTextAntialiasMode of an
By default, Direct2D renders text in ClearType mode. Factors that can downgrade the default quality to grayscale or aliased:
Use the system default. See Remarks.
Use ClearType antialiasing.
Use grayscale antialiasing.
Do not use antialiasing.
Describes whether a window is occluded.
-If the window was occluded the last time EndDraw was called, the next time the render target calls CheckWindowState, it returns
The window is not occluded.
The window is occluded.
Indicates whether the specified matrix is invertible.
-The matrix to test.
true if the matrix was inverted; otherwise, false.
Tries to invert the specified matrix.
-The matrix to invert.
true if the matrix was inverted; otherwise, false.
Creates a skew transformation that has the specified x-axis angle, y-axis angle, and center point.
-The x-axis skew angle, which is measured in degrees counterclockwise from the y-axis.
The y-axis skew angle, which is measured in degrees counterclockwise from the x-axis.
The center point of the skew operation.
When this method returns, contains the rotation transformation. You must allocate storate for this parameter.
Creates a factory object that can be used to create Direct2D resources.
-The threading model of the factory and the resources it creates.
A reference to the IID of
The level of detail provided to the debugging layer.
When this method returns, contains the address to a reference to the new factory.
If this function succeeds, it returns
The
Creates a rotation transformation that rotates by the specified angle about the specified point.
-The clockwise rotation angle, in degrees.
The point about which to rotate.
When this method returns, contains the new rotation transformation. You must allocate storage for this parameter.
Rotation occurs in the plane of the 2-D surface.
-Issues drawing commands to a GDI device context.
-To create an
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
To enable the DC render target to work with GDI, set its pixel format to
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
When you use an
It's possible for GDI to apply a GDI transform (through the SetWorldTransform method) or other effect to the same DC used by the render target, in which case GDI transforms the bitmap produced by Direct2D. Using a GDI transform to transform the Direct2D content has the potential to degrade the visual quality of the output, because you're transforming a bitmap for which antialiasing and subpixel positioning have already been calculated.
For example, suppose you use the render target to draw a scene that contains antialiased geometries and text. If you use a GDI transform to apply a scale transform to the DC and scale the scene so that it's 10 times larger, you'll see pixelization and jagged edges. (If, however, you applied a similar transform using Direct2D, the visual quality of the scene would not be degraded.)
In some cases, it might not be obvious that GDI is performing additional processing that might degrade the quality of the Direct2D content. For example, on a right-to-left (RTL) build of Windows, content rendered by an
Depending on the type of content being rendered, you might want to prevent the inversion. If the Direct2D content includes ClearType text, this inversion will degrade the quality of the text.
You can control RTL rendering behavior by using the SetLayout GDI function. To prevent the mirroring, call the SetLayout GDI function and specify LAYOUT_BITMAPORIENTATIONPRESERVED as the only value for the second parameter (do not combine it with LAYOUT_RTL), as shown in the following example:
SetLayout(m_hwnd, LAYOUT_BITMAPORIENTATIONPRESERVED);Binds the render target to the device context to which it issues drawing commands.
-The device context to which the render target issues drawing commands.
The dimensions of the handle to a device context (
If this method succeeds, it returns
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
-Represents the drawing state of a render target: the antialiasing mode, transform, tags, and text-rendering options.
-To create an
A drawing state block is a device-independent resource; you can create it once and retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the antialiasing mode, transform, and tags portion of the drawing state.
-When this method returns, contains the antialiasing mode, transform, and tags portion of the drawing state. You must allocate storage for this parameter.
Specifies the antialiasing mode, transform, and tags portion of the drawing state.
-The antialiasing mode, transform, and tags portion of the drawing state.
Specifies the text-rendering configuration of the drawing state.
-The text-rendering configuration of the drawing state, or
Retrieves the text-rendering configuration of the drawing state.
-When this method returns, contains the address of a reference to an
Retrieves or sets the antialiasing mode, transform, and tags portion of the drawing state.
-Retrieves or sets the text-rendering configuration of the drawing state.
-Represents an ellipse.
-To create an elipse geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Represents a geometry resource and defines a set of helper methods for manipulating and measuring geometric shapes. Interfaces that inherit from
There are several types of Direct2D geometry objects: a simple geometry (
Direct2D geometries enable you to describe two-dimensional figures and also offer many uses, such as defining hit-test regions, clip regions, and even animation paths.
Direct2D geometries are immutable and device-independent resources created by
Gets the bounds of the geometry after it has been widened by the specified stroke width and style and transformed by the specified matrix.
-The amount by which to widen the geometry by stroking its outline.
The style of the stroke that widens the geometry.
A transform to apply to the geometry after the geometry is transformed and after the geometry has been stroked.
When this method returns, contains the bounds of the widened geometry. You must allocate storage for this parameter.
Determines whether the geometry's stroke contains the specified point given the specified stroke thickness, style, and transform.
-The point to test for containment.
The thickness of the stroke to apply.
The style of stroke to apply.
The transform to apply to the stroked geometry.
When this method returns, contains a boolean value set to true if the geometry's stroke contains the specified point; otherwise, false. You must allocate storage for this parameter.
Indicates whether the area filled by the geometry would contain the specified point given the specified flattening tolerance.
-The point to test.
The transform to apply to the geometry prior to testing for containment, or
The numeric accuracy with which the precise geometric path and path intersection is calculated. Points missing the fill by less than the tolerance are still considered inside. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a
Describes the intersection between this geometry and the specified geometry. The comparison is performed by using the specified flattening tolerance.
-The geometry to test.
The transform to apply to inputGeometry, or
The maximum bounds on the distance between points in the polygonal approximation of the geometries. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to a value that describes how this geometry is related to inputGeometry. You must allocate storage for this parameter.
When interpreting the returned relation value, it is important to remember that the member
For more information about how to interpret other possible return values, see
Computes the outline of the geometry and writes the result to an
If this method succeeds, it returns
The Outline method allows the caller to produce a geometry with an equivalent fill to the input geometry, with the following additional properties:
Additionally, the Outline method can be useful in removing redundant portions of said geometries to simplify complex geometries. It can also be useful in combination with
Computes the area of the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The transform to apply to this geometry before computing its area, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this this method returns, contains a reference to the area of the transformed, flattened version of this geometry. You must allocate storage for this parameter.
Calculates the point and tangent vector at the specified distance along the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The distance along the geometry of the point and tangent to find. If this distance is less then 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry.
The transform to apply to the geometry before calculating the specified point and tangent, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to the tangent vector at the specified distance along the geometry. If the geometry is empty, this vector contains NaN as its x and y values. You must allocate storage for this parameter.
The location at the specified distance along the geometry. If the geometry is empty, this point contains NaN as its x and y values.
Widens the geometry by the specified stroke and writes the result to an
If this method succeeds, it returns
Gets the
Gets the
Creates Direct2D resources.
-The
A factory defines a set of CreateResource methods that can produce the following drawing resources:
To create an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so, this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note that the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU, however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Forces the factory to refresh any system defaults that it might have changed since factory creation.
-If this method succeeds, it returns
You should call this method before calling the GetDesktopDpi method, to ensure that the system DPI is current.
-Retrieves the current desktop dots per inch (DPI). To refresh this value, call ReloadSystemMetrics.
-Use this method to obtain the system DPI when setting physical pixel values, such as when you specify the size of a window.
- Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Transforms the specified geometry and stores the result as an
If this method succeeds, it returns
Like other resources, a transformed geometry the inherits the resource space and threading policy of the factory that created it. This object is immutable.
When stroking a transformed geometry with the DrawGeometry method, the stroke width is not affected by the transform applied to the geometry. The stroke width is only affected by the world transform.
-Creates an empty
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a render target that renders to a Microsoft Windows Imaging Component (WIC) bitmap.
-The bitmap that receives the rendering output of the render target.
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
Your application should create render targets once and hold onto them for the life of the application or until the
Creates an
If this method succeeds, it returns
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the
Creates a render target that draws to a DirectX Graphics Infrastructure (DXGI) surface.
-The
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
To write to a Direct3D surface, you obtain an
A DXGI surface render target is a type of
The DXGI surface render target and the DXGI surface must use the same DXGI format. If you specify the DXGI_FORMAT_UNKOWN format when you create the render target, it will automatically use the surface's format.
The DXGI surface render target does not perform DXGI surface synchronization.
For more information about creating and using DXGI surface render targets, see the Direct2D and Direct3D Interoperability Overview.
To work with Direct2D, the Direct3D device that provides the
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Creates a render target that draws to a Windows Graphics Device Interface (GDI) device context.
-The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. To enable the device context (DC) render target to work with GDI, set the DXGI format to
When this method returns, dcRenderTarget contains the address of the reference to the
If this method succeeds, it returns
Before you can render with a DC render target, you must use the render target's BindDC method to associate it with a GDI DC. Do this for each different DC and whenever there is a change in the size of the area you want to draw to.
To enable the DC render target to work with GDI, set the render target's DXGI format to
Your application should create render targets once and hold on to them for the life of the application or until the render target's EndDraw method returns the
Represents a composite geometry, composed of other
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one.
CreatingTo create a
Direct2D geometries are immutable and device-independent resources created by
Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-A value that indicates how the intersecting areas of the geometries contained in this geometry group are combined.
Indicates the number of geometry objects in the geometry group.
-The number of geometries in the
Retrieves the geometries in the geometry group.
-When this method returns, contains the address of a reference to an array of geometries to be filled by this method. The length of the array is specified by the geometryCount parameter. If the array is
A value indicating the number of geometries to return in the geometries array. If this value is less than the number of geometries in the geometry group, the remaining geometries are omitted. If this value is larger than the number of geometries in the geometry group, the extra geometries are set to
The returned geometries are referenced and counted, and the caller must release them.
-Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-Indicates the number of geometry objects in the geometry group.
-Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Specifies the method used to determine which points are inside the geometry described by this geometry sink and which points are outside.
-The method used to determine whether a given point is part of the geometry.
The fill mode defaults to
Specifies stroke and join options to be applied to new segments added to the geometry sink.
-Stroke and join options to be applied to new segments added to the geometry sink.
After this method is called, the specified segment flags are applied to each segment subsequently added to the sink. The segment flags are applied to every additional segment until this method is called again and a different set of segment flags is specified.
-Starts a new figure at the specified point.
-The point at which to begin the new figure.
Whether the new figure should be hollow or filled.
If this method is called while a figure is currently in progress, the interface is invalidated and all future methods will fail.
-Creates a sequence of lines using the specified points and adds them to the geometry sink.
-A reference to an array of one or more points that describe the lines to draw. A line is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the first point in the array. if the array contains additional points, a line is drawn from the first point to the second point in the array, from the second point to the third point, and so on.
The number of points in the points array.
Creates a sequence of cubic Bezier curves and adds them to the geometry sink.
-A reference to an array of Bezier segments that describes the Bezier curves to create. A curve is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the end point of the first Bezier segment in the array. if the array contains additional Bezier segments, each subsequent Bezier segment uses the end point of the preceding Bezier segment as its start point.
The number of Bezier segments in the beziers array.
Ends the current figure; optionally, closes it.
-A value that indicates whether the current figure is closed. If the figure is closed, a line is drawn between the current point and the start point specified by BeginFigure.
Calling this method without a matching call to BeginFigure places the geometry sink in an error state; subsequent calls are ignored, and the overall failure will be returned when the Close method is called.
-Closes the geometry sink, indicates whether it is in an error state, and resets the sink's error state.
-If this method succeeds, it returns
Do not close the geometry sink while a figure is still in progress; doing so puts the geometry sink in an error state. For the close operation to be successful, there must be one EndFigure call for each call to BeginFigure.
After calling this method, the geometry sink might not be usable. Direct2D implementations of this interface do not allow the geometry sink to be modified after it is closed, but other implementations might not impose this restriction.
-Creates a line segment between the current point and the specified end point and adds it to the geometry sink.
-The end point of the line to draw.
Creates a cubic Bezier curve between the current point and the specified end point.
-A structure that describes the control points and end point of the Bezier curve to add.
Creates a quadratic Bezier curve between the current point and the specified endpoint.
-A structure that describes the control point and the endpoint of the quadratic Bezier curve to add.
Adds a sequence of quadratic Bezier segments as an array in a single call.
-An array of a sequence of quadratic Bezier segments.
A value indicating the number of quadratic Bezier segments in beziers.
Adds a single arc to the path geometry.
-The arc segment to add to the figure.
Represents an collection of
To create an
A gradient stop collection is a device-dependent resource: your application should create gradient stop collections after it initializes the render target with which the gradient stop collection will be used, and recreate the gradient stop collection whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Retrieves the number of gradient stops in the collection.
-The number of gradient stops in the collection.
Copies the gradient stops from the collection into an array of
Gradient stops are copied in order of position, starting with the gradient stop with the smallest position value and progressing to the gradient stop with the largest position value.
-Indicates the gamma space in which the gradient stops are interpolated.
-The gamma space in which the gradient stops are interpolated.
Indicates the behavior of the gradient outside the normalized gradient range.
-The behavior of the gradient outside the [0,1] normalized gradient range.
Retrieves the number of gradient stops in the collection.
-Indicates the gamma space in which the gradient stops are interpolated.
-Indicates the behavior of the gradient outside the normalized gradient range.
-Represents the backing store required to render a layer.
-To create a layer, call the CreateLayer method of the render target where the layer will be used. To draw to a layer, push the layer to the render target stack by calling the PushLayer method. After you have finished drawing to the layer, call the PopLayer method.
Between PushLayer and PopLayer calls, the layer is in use and cannot be used by another render target.
If the size of the layer is not specified, the corresponding PushLayer call determines the minimum layer size, based on the layer content bounds and the geometric mask. The layer resource can be larger than the size required by PushLayer without any rendering artifacts.
If the size of a layer is specified, or if the layer has been used and the required backing store size as calculated during PushLayer is larger than the layer, then the layer resource is expanded on each axis monotonically to ensure that it is large enough. The layer resource never shrinks in size.
CreatingTo create a layer, call the CreateLayer method of the render target where the layer will be used.
A layer is a device-dependent resource: your application should create layers after it initializes the render target with which the layers will be used, and recreate the layers whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Gets the size of the layer in device-independent pixels.
-The size of the layer in device-independent pixels.
Gets the size of the layer in device-independent pixels.
-Paints an area with a linear gradient.
-An
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush start point and end point are also transformed.
It is possible to specify a gradient axis that does not completely fill the area that is being painted. When this occurs, the
To create a linear gradient brush, use the
A linear gradient brush is a device-dependent resource: your application should create linear gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Sets the starting coordinates of the linear gradient in the brush's coordinate space.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Sets the ending coordinates of the linear gradient in the brush's coordinate space.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the starting coordinates of the linear gradient.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the ending coordinates of the linear gradient.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Retrieves or sets the starting coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves or sets the ending coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Represents a set of vertices that form a list of triangles.
-To create a mesh, call the
A mesh is a device-dependent resource: your application should create meshes after it initializes the render target with which the meshes will be used, and recreate the meshes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Opens the mesh for population.
-When this method returns, contains a reference to a reference to an
If this method succeeds, it returns
Represents a complex shape that may be composed of arcs, curves, and lines.
-An
To create a path geometry, use the
Retrieves the geometry sink that is used to populate the path geometry with figures and segments.
-When this method returns, geometrySink contains the address of a reference to the geometry sink that is used to populate the path geometry with figures and segments. This parameter is passed uninitialized.
Because path geometries are immutable and can only be populated once, it is an error to call Open on a path geometry more than once.
Note that the fill mode defaults to
Copies the contents of the path geometry to the specified
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-A reference that receives the number of segments in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of figures in the path geometry.
-A reference that receives the number of figures in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-Retrieves the number of figures in the path geometry.
-Paints an area with a radial gradient.
-The
The brush maps the gradient stop position 0.0f of the gradient origin, and the position 1.0f is mapped to the ellipse boundary. When the gradient origin is within the ellipse, the contents of the ellipse enclose the entire [0, 1] range of the brush gradient stops. If the gradient origin is outside the bounds of the ellipse, the brush still works, but its gradient is not well-defined.
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps just one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush ellipse and gradient origin are also transformed.
It is possible to specify an ellipse that does not completely fill area being painted. When this occurs, the
To create a radial gradient brush, use the
A radial gradient brush is a device-dependent resource: your application should create radial gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Specifies the center of the gradient ellipse in the brush's coordinate space.
-The center of the gradient ellipse, in the brush's coordinate space.
Specifies the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse.
Specifies the x-radius of the gradient ellipse, in the brush's coordinate space.
-The x-radius of the gradient ellipse. This value is in the brush's coordinate space.
Specifies the y-radius of the gradient ellipse, in the brush's coordinate space.
-The y-radius of the gradient ellipse. This value is in the brush's coordinate space.
Retrieves the center of the gradient ellipse.
-The center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the x-radius of the gradient ellipse.
-The x-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the y-radius of the gradient ellipse.
-The y-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the
Retrieves or sets the center of the gradient ellipse.
-Retrieves or sets the offset of the gradient origin relative to the gradient ellipse's center.
-Retrieves or sets the x-radius of the gradient ellipse.
-Retrieves or sets the y-radius of the gradient ellipse.
-Retrieves the
Describes a two-dimensional rectangle.
-To create a rectangle geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Contains a reference to a rectangle that describes the rectangle geometry's dimensions when this method returns. You must allocate storage for this parameter.
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-A reference that receives a rounded rectangle that describes this rounded rectangle geometry. You must allocate storage for this parameter.
Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Paints an area with a solid color.
-To create a solid color brush, use the
A solid color brush is a device-dependent resource. (For more information about resources, see Resources Overview.)
-Specifies the color of this solid-color brush.
-The color of this solid-color brush.
To help create colors, Direct2D provides the ColorF class. It offers several helper methods for creating colors and provides a set or predefined colors.
-Retrieves the color of the solid color brush.
-The color of this solid color brush.
Retrieves or sets the color of the solid color brush.
-Describes the caps, miter limit, line join, and dash information for a stroke.
-To create a stroke style, use the
A stroke style is a device-indenpendent resource; you can create it once then retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the type of shape used at the beginning of a stroke.
-The type of shape used at the beginning of a stroke.
Retrieves the type of shape used at the end of a stroke.
-The type of shape used at the end of a stroke.
Gets a value that specifies how the ends of each dash are drawn.
-A value that specifies how the ends of each dash are drawn.
Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-A positive number greater than or equal to 1.0f that describes the limit on the ratio of the miter length to half the stroke's thickness.
Retrieves the type of joint used at the vertices of a shape's outline.
-A value that specifies the type of joint used at the vertices of a shape's outline.
Retrieves a value that specifies how far in the dash sequence the stroke will start.
-A value that specifies how far in the dash sequence the stroke will start.
Gets a value that describes the stroke's dash pattern.
-A value that describes the predefined dash pattern used, or
If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-The number of entries in the dashes array if the stroke is dashed; otherwise, 0.
Copies the dash pattern to the specified array.
-A reference to an array that will receive the dash pattern. The array must be able to contain at least as many elements as specified by dashesCount. You must allocate storage for this array.
The number of dashes to copy. If this value is less than the number of dashes in the stroke style's dashes array, the returned dashes are truncated to dashesCount. If this value is greater than the number of dashes in the stroke style's dashes array, the extra dashes are set to 0.0f. To obtain the actual number of dashes in the stroke style's dashes array, use the GetDashesCount method.
The dashes are specified in units that are a multiple of the stroke width, with subsequent members of the array indicating the dashes and gaps between dashes: the first entry indicates a filled dash, the second a gap, and so on.
-Retrieves the type of shape used at the beginning of a stroke.
-Retrieves the type of shape used at the end of a stroke.
-Gets a value that specifies how the ends of each dash are drawn.
-Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-Retrieves the type of joint used at the vertices of a shape's outline.
-Retrieves a value that specifies how far in the dash sequence the stroke will start.
-Gets a value that describes the stroke's dash pattern.
-If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-Populates an
Populates an
Copies the specified triangles to the sink.
-An array of
The number of triangles to copy from the triangles array.
Closes the sink and returns its error status.
-If this method succeeds, it returns
Represents a geometry that has been transformed.
-Using an
To create an
Direct2D geometries are immutable and device-independent resources created by
Retrieves the source geometry of this transformed geometry object.
-When this method returns, contains a reference to a reference to the source geometry for this transformed geometry object. This parameter is passed uninitialized.
Retrieves the matrix used to transform the
Retrieves the source geometry of this transformed geometry object.
-Retrieves the matrix used to transform the
Renders drawing instructions to a window.
-As is the case with other render targets, you must call BeginDraw before issuing drawing commands. After you've finished drawing, call EndDraw to indicate that drawing is finished and to release access to the buffer backing the render target. For
A hardware render target's back-buffer is the size specified by GetPixelSize. If EndDraw presents the buffer, this bitmap is stretched to cover the surface where it is presented: the entire client area of the window. This stretch is performed using bilinear filtering if the render target is rendering in hardware and using nearest-neighbor filtering if the rendering target is using software. (Typically, an application will call Resize to ensure the pixel size of the render target and the pixel size of the destination match, and no scaling is necessary, though this is not a requirement.)
In the case where a window straddles adapters, Direct2D ensures that the portion of the off-screen render target is copied from the adapter where rendering is occurring to the adapter that needs to display the contents. If the adapter a render target is on has been removed or the driver upgraded while the application is running, this is returned as an error in the EndDraw call. In this case, the application should create a new render target and resources as necessary. -
CreatingTo create an
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Indicates whether the
A value that indicates whether the
Note??If the window was occluded the last time that EndDraw was called, the next time that the render target calls CheckWindowState, it will return
After this method is called, the contents of the render target's back-buffer are not defined, even if the
Returns the
The
Returns the
Describes an elliptical arc between two points.
-The end point of the arc.
The x-radius and y-radius of the arc.
A value that specifies how many degrees in the clockwise direction the ellipse is rotated relative to the current coordinate system.
A value that specifies whether the arc sweep is clockwise or counterclockwise.
A value that specifies whether the given arc is larger than 180 degrees.
Represents a cubic bezier segment drawn between two points.
-A cubic Bezier curve is defined by four points: a start point, an end point (point3), and two control points (point1 and point2). A Bezier segment does not contain a property for the starting point of the curve; it defines only the end point. The beginning point of the curve is the current point of the path to which the Bezier curve is added.
The two control points of a cubic Bezier curve behave like magnets, attracting portions of what would otherwise be a straight line toward themselves and producing a curve. The first control point, point1, affects the beginning portion of the curve; the second control point, point2, affects the ending portion of the curve.
Note??The curve doesn't necessarily pass through either of the control points; each control point moves its portion of the line toward itself, but not through itself.
-The first control point for the Bezier segment.
The second control point for the Bezier segment.
The end point for the Bezier segment.
Describes the extend modes and the interpolation mode of an
Describes the opacity and transformation of a brush.
-This structure is used when creating a brush. For convenience, Direct2D provides the D2D1::BrushProperties function for creating
After creating a brush, you can change its opacity or transform by calling the SetOpacity or SetTransform methods.
-A value between 0.0f and 1.0f, inclusive, that specifies the degree of opacity of the brush.
The transformation that is applied to the brush.
Describes the drawing state of a render target.
-The antialiasing mode for subsequent nontext drawing operations.
The antialiasing mode for subsequent text and glyph drawing operations.
A label for subsequent drawing operations.
A label for subsequent drawing operations.
The transformation to apply to subsequent drawing operations.
Contains the debugging level of an
To enable debugging, you must install the Direct2D Debug Layer.
-Contains the position and color of a gradient stop.
-Gradient stops can be specified in any order if they are at different positions. Two stops may share a position. In this case, the first stop specified is treated as the "low" stop (nearer 0.0f) and subsequent stops are treated as "higher" (nearer 1.0f). This behavior is useful if a caller wants an instant transition in the middle of a stop.
Typically, there are at least two points in a collection, although creation with only one stop is permitted. For example, one point is at position 0.0f, another point is at position 1.0f, and additional points are distributed in the [0, 1] range. Where the gradient progression is beyond the range of [0, 1], the stops are stored, but may affect the gradient.
When drawn, the [0, 1] range of positions is mapped to the brush, in a brush-dependent way. For details, see
Gradient stops with a position outside the [0, 1] range cannot be seen explicitly, but they can still affect the colors produced in the [0, 1] range. For example, a two-stop gradient 0.0f, Black}, {2.0f, White is indistinguishable visually from 0.0f, Black}, {1.0f, Mid-level gray. Also, the colors are clamped before interpolation.
-A value that indicates the relative position of the gradient stop in the brush. This value must be in the [0.0f, 1.0f] range if the gradient stop is to be seen explicitly.
The color of the gradient stop.
Contains the
Use this structure when you call the CreateHwndRenderTarget method to create a new
For convenience, Direct2D provides the D2D1::HwndRenderTargetProperties function for creating new
Contains the starting point and endpoint of the gradient axis for an
Use this method when creating new
The following illustration shows how a linear gradient changes as you change its start and end points. For the first gradient, the start point is set to (0,0) and the end point to (150, 50); this creates a diagonal gradient that starts at the upper-left corner and extends to the lower-right corner of the area being painted. When you set the start point to (0, 25) and the end point to (150, 25), a horizontal gradient is created. Similarly, setting the start point to (75, 0) and the end point to (75, 50) creates a vertical gradient. Setting the start point to (0, 50) and the end point to (150, 0) creates a diagonal gradient that starts at the lower-left corner and extends to the upper-right corner of the area being painted.
-Contains the data format and alpha mode for a bitmap or render target.
-For more information about the pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
-A value that specifies the size and arrangement of channels in each pixel.
A value that specifies whether the alpha channel is using pre-multiplied alpha, straight alpha, whether it should be ignored and considered opaque, or whether it is unkown.
Contains the control point and end point for a quadratic Bezier segment.
-The control point of the quadratic Bezier segment.
The end point of the quadratic Bezier segment.
Contains the gradient origin offset and the size and position of the gradient ellipse for an
Different values for center, gradientOriginOffset, radiusX and/or radiusY produce different gradients. The following illustration shows several radial gradients that have different gradient origin offsets, creating the appearance of the light illuminating the circles from different angles.
For convenience, Direct2D provides the D2D1::RadialGradientBrushProperties function for creating new D2D1_RADIAL_GRADIENT_BRUSH structures.
-Contains rendering options (hardware or software), pixel format, DPI information, remoting options, and Direct3D support requirements for a render target.
-Use this structure when creating a render target, or use it with the
As a convenience, Direct2D provides the D2D1::RenderTargetProperties helper function for creating
Not all render targets support hardware rendering. For a list, see the Render Targets Overview.
Using Default DPI SettingsTo use the default DPI, set dpiX and dpiY to 0. The default DPI varies depending on the render target:
To use the default DPI setting, both dpiX and dpiY must be set to 0. Setting only one value to 0 causes an E_INVALIDARG error when attempting to create a render target.
-A value that specifies whether the render target should force hardware or software rendering. A value of
The pixel format and alpha mode of the render target. You can use the D2D1::PixelFormat function to create a pixel format that specifies that Direct2D should select the pixel format and alpha mode for you. For a list of pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
The horizontal DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
The vertical DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
A value that specifies how the render target is remoted and whether it should be GDI-compatible. Set to
A value that specifies the minimum Direct3D feature level required for hardware rendering. If the specified minimum level is not available, the render target uses software rendering if the type member is set to
Contains the dimensions and corner radii of a rounded rectangle.
-Each corner of the rectangle specified by the rect is replaced with a quarter ellipse, with a radius in each direction specified by radiusX and radiusY.
If the radiusX is greater than or equal to half the width of the rectangle, and the radiusY is greater than or equal to one-half the height, the rounded rectangle is an ellipse with the same width and height of the rect.
Even when both radiuX and radiusY are zero, the rounded rectangle is different from a rectangle., When stroked, the corners of the rounded rectangle are roundly joined, not mitered (square).
-The coordinates of the rectangle.
The x-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
The y-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
Describes the stroke that outlines a shape.
-The following illustration shows different dashOffset values for the same custom dash style.
-The cap applied to the start of all the open figures in a stroked geometry.
The cap applied to the end of all the open figures in a stroked geometry.
The shape at either end of each dash segment.
A value that describes how segments are joined. This value is ignored for a vertex if the segment flags specify that the segment should have a smooth join.
The limit of the thickness of the join on a mitered corner. This value is always treated as though it is greater than or equal to 1.0f.
A value that specifies whether the stroke has a dash pattern and, if so, the dash style.
A value that specifies an offset in the dash sequence. A positive dash offset value shifts the dash pattern, in units of stroke width, toward the start of the stroked geometry. A negative dash offset value shifts the dash pattern, in units of stroke width, toward the end of the stroked geometry.
Contains the three vertices that describe a triangle.
-The first vertex of a triangle.
The second vertex of a triangle.
The third vertex of a triangle.
Contains the content bounds, mask information, opacity settings, and other options for a layer resource.
-The content bounds of the layer. Content outside these bounds is not guaranteed to render.
The geometric mask specifies the area of the layer that is composited into the render target.
A value that specifies the antialiasing mode for the geometricMask.
A value that specifies the transform that is applied to the geometric mask when composing the layer.
An opacity value that is applied uniformly to all resources in the layer when compositing to the target.
A brush that is used to modify the opacity of the layer. The brush - is mapped to the layer, and the alpha channel of each mapped brush pixel is multiplied against the corresponding layer pixel.
A value that specifies whether the layer intends to render text with ClearType antialiasing.
Specifies the identifiers of the metadata items in an 8BIM IPTC digest metadata block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_BLOB] The embedded IPTC digest value.
Specifies the identifiers of the metadata items in an 8BIM IPTC block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UNKNOWN] The IPTC block embedded in this 8BIM IPTC block.
Specifies the identifiers of the metadata items in an 8BIMResolutionInfo block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UI4] The horizontal resolution of the image.
[VT_UI2] The units that the horizontal resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image width is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
[VT_UI4] The vertical resolution of the image.
[VT_UI2] The units that the vertical resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image height is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
Specifies the desired alpha channel usage.
-Use alpha channel.
Use a pre-multiplied alpha channel.
Ignore alpha channel.
Specifies the desired cache usage.
-The CreateBitmap of the
Do not cache the bitmap.
Cache the bitmap when needed.
Cache the bitmap at initialization.
Specifies the capabilities of the decoder.
-Decoder recognizes the image was encoded with an encoder produced by the same vendor.
Decoder can decode all the images within an image container.
Decoder can decode some of the images within an image container.
Decoder can enumerate the metadata blocks within a container format.
Decoder can find and decode a thumbnail.
Specifies the type of dither algorithm to apply when converting between image formats.
-A solid color algorithm without dither.
A solid color algorithm without dither.
A 4x4 ordered dither algorithm.
An 8x8 ordered dither algorithm.
A 16x16 ordered dither algorithm.
A 4x4 spiral dither algorithm.
An 8x8 spiral dither algorithm.
A 4x4 dual spiral dither algorithm.
An 8x8 dual spiral dither algorithm.
An error diffusion algorithm.
Specifies the cache options available for an encoder.
-The encoder is cached in memory. This option is not supported.
The encoder is cached to a temporary file. This option is not supported.
The encoder is not cached.
Specifies the sampling or filtering mode to use when scaling an image.
-A nearest neighbor interpolation algorithm. Also known as nearest pixel or point interpolation.
The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.
A bilinear interpolation algorithm.
The output pixel values are computed as a weighted average of the nearest four pixels in a 2x2 grid.
A bicubic interpolation algorithm.
Destination pixel values are computed as a weighted average of the nearest sixteen pixels in a 4x4 grid.
A Fant resampling algorithm.
Destination pixel values are computed as a weighted average of the all the pixels that map to the new pixel.
Specifies access to an
Specifies the type of palette used for an indexed image format.
-An arbitrary custom palette provided by caller.
An optimal palette generated using a median-cut algorithm. Derived from the colors in an image.
A black and white palette.
A palette that has its 8-color on-off primaries and the 16 system colors added. With duplicates removed, 16 colors are available.
A palette that has 3 intensity levels of each primary: 27-color on-off primaries and the 16 system colors added. With duplicates removed, 35 colors are available.
A palette that has 4 intensity levels of each primary: 64-color on-off primaries and the 16 system colors added. With duplicates removed, 72 colors are available.
A palette that has 5 intensity levels of each primary: 125-color on-off primaries and the 16 system colors added. With duplicates removed, 133 colors are available.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as WICBitmapPaletteFixedHalftoneWeb.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as
A palette that has its 252-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has its 256-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has 4 shades of gray.
A palette that has 16 shades of gray.
A palette that has 256 shades of gray.
Specifies the flip and rotation transforms.
-A rotation of 0 degrees.
A clockwise rotation of 90 degrees.
A clockwise rotation of 180 degrees.
A clockwise rotation of 270 degrees.
A horizontal flip. Pixels are flipped around the vertical y-axis.
A vertical flip. Pixels are flipped around the horizontal x-axis.
Specifies the color context types.
-An uninitialized color context.
A color context profile.
An EXIF color space color context.
Specifies component enumeration options.
-Enumerate signed components.
Force a read of the registry when enumerating components.
Enumerate disabled components.
Enumerate unsigned components.
Enumerate only built in components.
Specifies the component signing status.
-A signed component.
An unsigned component
A component is safe.
Components that do not have a binary component to sign, such as a pixel format, should return this value.
A component has been disabled.
Specifies the type of Windows Imaging Component (WIC) component.
-A WIC decoder.
A WIC encoder.
A WIC pixel converter.
A WIC metadata reader.
A WIC metadata writer.
A WIC pixel format.
All WIC components.
Specifies decode options.
-Cache metadata when needed.
Cache metadata when decoder is loaded.
Specifies the application extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_UI1 | VT_VECTOR] Indicates a string that identifies the application.
[VT_UI1 | VT_VECTOR] Indicates data that is exposed by the application.
Specifies the comment extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_LPSTR] Indicates the comment text.
Specifies the graphic control extension metadata properties that define the transitions between each frame animation for Graphics Interchange Format (GIF) images.
-[VT_UI1] Indicates the disposal requirements. 0 - no disposal, 1 - do not dispose, 2 - restore to background color, 3 - restore to previous.
[VT_BOOL] Indicates the user input flag. TRUE if user input should advance to the next frame; otherwise,
[VT_BOOL] Indicates the transparency flag. TRUE if a transparent color in is in the color table for this frame; otherwise,
[VT_UI2] Indicates how long to display the next frame before advancing to the next frame, in units of 1/100th of a second.
[VT_UI1] Indicates which color in the palette should be treated as transparent.
Specifies the image descriptor metadata properties for Graphics Interchange Format (GIF) frames.
-[VT_UI2] Indicates the X offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates the Y offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates width of this frame, in pixels.
[VT_UI2] Indicates height of this frame, in pixels.
[VT_BOOL] Indicates the local color table flag. TRUE if global color table is present; otherwise,
[VT_BOOL] Indicates the interlace flag. TRUE if image is interlaced; otherwise,
[VT_BOOL] Indicates the sorted color table flag. TRUE if the color table is sorted from most frequently to least frequently used color; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
Specifies the logical screen descriptor properties for Graphics Interchange Format (GIF) metadata.
-[VT_UI1 | VT_VECTOR] Indicates the signature property.
[VT_UI2] Indicates the width in pixels.
[VT_UI2] Indicates the height in pixels.
[VT_BOOL] Indicates the global color table flag. TRUE if a global color table is present; otherwise,
[VT_UI1] Indicates the color resolution in bits per pixel.
[VT_BOOL] Indicates the sorted color table flag. TRUE if the table is sorted; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
[VT_UI1] Indicates the index within the color table to use for the background (pixels not defined in the image).
[VT_UI1] Indicates the factor used to compute an approximation of the aspect ratio.
Specifies the JPEG chrominance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a chrominance table.
Specifies the JPEG comment properties.
-Indicates the metadata property is comment text.
Specifies the JPEG luminance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a luminance table.
Specifies the JPEG YCrCB subsampling options.
-The native JPEG encoder uses
The default subsampling option.
Subsampling option that uses both horizontal and vertical decimation.
Subsampling option that uses horizontal decimation .
Subsampling option that uses no decimation.
Specifies named white balances for raw images.
-The default white balance.
A daylight white balance.
A cloudy white balance.
A shade white balance.
A tungsten white balance.
A fluorescent white balance.
Daylight white balance.
A flash white balance.
A custom white balance. This is typically used when using a picture (grey-card) as white balance.
An automatic balance.
An "as shot" white balance.
Specifies the Portable Network Graphics (PNG) background (bKGD) chunk metadata properties.
-Indicates the background color. There are three possible types, depending on the image's pixel format.
Specifies the index of the background color in an image with an indexed pixel format.
Specifies the background color in a grayscale image.
Specifies the background color in an RGB image as three USHORT values: {0xRRRR, 0xGGGG, 0xBBBB}.
Specifies the Portable Network Graphics (PNG) cHRM chunk metadata properties for CIE XYZ chromaticity.
-[VT_UI4] Indicates the whitepoint x value ratio.
[VT_UI4] Indicates the whitepoint y value ratio.
[VT_UI4] Indicates the red x value ratio.
[VT_UI4] Indicates the red y value ratio.
[VT_UI4] Indicates the green x value ratio.
[VT_UI4] Indicates the green y value ratio.
[VT_UI4] Indicates the blue x value ratio.
[VT_UI4] Indicates the blue y value ratio.
Specifies the Portable Network Graphics (PNG) filters available for compression optimization.
-Indicates an unspecified PNG filter. This enables WIC to algorithmically choose the best filtering option for the image.
Indicates no PNG filter.
Indicates a PNG sub filter.
Indicates a PNG up filter.
Indicates a PNG average filter.
Indicates a PNG paeth filter.
Indicates a PNG adaptive filter. This enables WIC to choose the best filtering mode on a per-scanline basis.
Specifies the Portable Network Graphics (PNG) gAMA chunk metadata properties.
-[VT_UI4] Indicates the gamma value.
Specifies the Portable Network Graphics (PNG) hIST chunk metadata properties.
-[VT_VECTOR | VT_UI2] Indicates the approximate usage frequency of each color in the color palette.
Specifies the Portable Network Graphics (PNG) iCCP chunk metadata properties.
-[VT_LPSTR] Indicates the International Color Consortium (ICC) profile name.
[VT_VECTOR | VT_UI1] Indicates the embedded ICC profile.
Specifies the Portable Network Graphics (PNG) iTXT chunk metadata properties.
-[VT_LPSTR] Indicates the keywords in the iTXT metadata chunk.
[VT_UI1] Indicates whether the text in the iTXT chunk is compressed. 1 if the text is compressed; otherwise, 0.
[VT_LPSTR] Indicates the human language used by the translated keyword and the text.
[VT_LPWSTR] Indicates a translation of the keyword into the language indicated by the language tag.
[VT_LPWSTR] Indicates additional text in the iTXT metadata chunk.
Specifies the Portable Network Graphics (PNG) sRGB chunk metadata properties.
-[VT_UI1] Indicates the rendering intent for an sRGB color space image. The rendering intents have the following meaning.
| Value | Meaning |
|---|---|
| 0 | Perceptual |
| 1 | Relative colorimetric |
| 2 | Saturation |
| 3 | Absolute colorimetric |
?
Specifies the Portable Network Graphics (PNG) tIME chunk metadata properties.
-[VT_UI2] Indicates the year of the last modification.
[VT_UI1] Indicates the month of the last modification.
[VT_UI1] Indicates day of the last modification.
[VT_UI1] Indicates the hour of the last modification.
[VT_UI1] Indicates the minute of the last modification.
[VT_UI1] Indicates the second of the last modification.
Specifies when the progress notification callback should be called.
-The callback should be called when codec operations begin.
The callback should be called when codec operations end.
The callback should be called frequently to report status.
The callback should be called on all available progress notifications.
Specifies the progress operations to receive notifications for.
-Receive copy pixel operation.
Receive write pixel operation.
Receive all progress operations available.
Specifies the capability support of a raw image.
-The capability is not supported.
The capability supports only get operations.
The capability supports get and set operations.
Specifies the parameter set used by a raw codec.
-An as shot parameter set.
A user adjusted parameter set.
A codec adjusted parameter set.
Specifies the render intent of the next CopyPixels call.
-Specifies the rotation capabilities of the codec.
-Rotation is not supported.
Set operations for rotation is not supported.
90 degree rotations are supported.
All rotation angles are supported.
Specifies the access level of a Windows Graphics Device Interface (GDI) section.
-Indicates a read only access level.
Indicates a read/write access level.
Specifies the Tagged Image File Format (TIFF) compression options.
-Indicates a suitable compression algorithm based on the image and pixel format.
Indicates no compression.
Indicates a CCITT3 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a CCITT4 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a LZW compression algorithm.
Indicates a RLE compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a ZIP compression algorithm.
Indicates an LZWH differencing algorithm.
Defines methods that add the concept of writeability and static in-memory representations of bitmaps to
Because of to the internal memory representation implied by the
Exposes methods that refers to a source from which pixels are retrieved, but cannot be written back to.
-This interface provides a common way of accessing and linking together bitmaps, decoders, format converters, and scalers. Components that implement this interface can be connected together in a graph to pull imaging data through.
This interface defines only the notion of readability or being able to produce pixels. Modifying or writing to a bitmap is considered to be a specialization specific to bitmaps which have storage and is defined in the descendant interface
Retrieves the pixel width and height of the bitmap.
-A reference that receives the pixel width of the bitmap.
A reference that receives the pixel height of the bitmap
If this method succeeds, it returns
Retrieves the pixel format of the bitmap source..
-Receives the pixel format
If this method succeeds, it returns
The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the sampling rate between pixels and physical world measurements.
-A reference that receives the x-axis dpi resolution.
A reference that receives the y-axis dpi resolution.
If this method succeeds, it returns
Some formats, such as GIF and ICO, do not have full DPI support. For GIF, this method calculates the DPI values from the aspect ratio, using a base DPI of (96.0, 96.0). The ICO format does not support DPI at all, and the method always returns (96.0,96.0) for ICO images.
Additionally, WIC itself does not transform images based on the DPI values in an image. It is up to the caller to transform an image based on the resolution returned.
-Retrieves the color table for indexed pixel formats.
-An
Returns one of the following values.
| Return code | Description |
|---|---|
| | The palette was unavailable. |
| | The palette was successfully copied. |
?
If the
Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
The size of the buffer.
A reference to the buffer.
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Retrieves the pixel format of the bitmap source..
-The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the pixel width and height of the bitmap.
-Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-The palette to use for conversion.
If this method succeeds, it returns
Changes the physical resolution of the image.
-The horizontal resolution.
The vertical resolution.
If this method succeeds, it returns
This method has no effect on the actual pixels or samples stored in the bitmap. Instead the interpretation of the sampling rate is modified. This means that a 96 DPI image which is 96 pixels wide is one inch. If the physical resolution is modified to 48 DPI, then the bitmap is considered to be 2 inches wide but has the same number of pixels. If the resolution is less than REAL_EPSILON (1.192092896e-07F) the error code
Provides access to a rectangular area of the bitmap.
-The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-Exposes methods that produce a clipped version of the input bitmap for a specified rectangular region of interest.
-Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Exposes methods that provide information about a particular codec.
-Exposes methods that provide component information.
-Retrieves the component's
If this method succeeds, it returns
Retrieves the component's class identifier (CLSID)
-A reference that receives the component's CLSID.
If this method succeeds, it returns
Retrieves the signing status of the component.
-A reference that receives the
If this method succeeds, it returns
Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the name of component's author.
-The size of the wzAuthor buffer.
A reference that receives the name of the component's author. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's authors name. The author name is optional; if an author name is not specified by the component, the length returned is 0.
If this method succeeds, it returns
If cchAuthor is 0 and wzAuthor is
Retrieves the vendor
A reference that receives the component's vendor
If this method succeeds, it returns
Retrieves the component's version.
-The size of the wzVersion buffer.
A reference that receives a culture invariant string of the component's version.
A reference that receives the actual length of the component's version. The version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's specification version.
-The size of the wzSpecVersion buffer.
When this method returns, contain a culture invarient string of the component's specification version. The version form is NN.NN.NN.NN.
A reference that receives the actual length of the component's specification version. The specification version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a spec version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's friendly name, which is a human-readable display name for the component.
-The size of the wzFriendlyName buffer.
A reference that receives the friendly name of the component. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's friendly name.
If this method succeeds, it returns
If cchFriendlyName is 0 and wzFriendlyName is
Retrieves the component's
Retrieves the component's class identifier (CLSID)
-Retrieves the signing status of the component.
-Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the vendor
Retrieves the container
Receives the container
If this method succeeds, it returns
Retrieves the pixel formats the codec supports.
-The size of the pguidPixelFormats array. Use 0 on first call to determine the needed array size.
Receives the supported pixel formats. Use
The array size needed to retrieve all supported pixel formats.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the array size needed to retrieve all the supported pixel formats by calling it with cFormats set to 0 and pguidPixelFormats set to
Retrieves the color manangement version number the codec supports.
-The size of the version buffer. Use 0 on first call to determine needed buffer size.
Receives the color management version number. Use
The actual buffer size needed to retrieve the full color management version number.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchColorManagementVersion set to 0 and wzColorManagementVersion set to
Retrieves the name of the device manufacture associated with the codec.
-The size of the device manufacture's name. Use 0 on first call to determine needed buffer size.
Receives the device manufacture's name. Use
The actual buffer size needed to retrieve the device manufacture's name.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceManufacturer set to 0 and wzDeviceManufacturer set to
Retrieves a comma delimited list of device models associated with the codec.
-The size of the device models buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of device model names associated with the codec. Use
The actual buffer size needed to retrieve all of the device model names.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceModels set to 0 and wzDeviceModels set to
Retrieves a comma delimited sequence of mime types associated with the codec.
-The size of the mime types buffer. Use 0 on first call to determine needed buffer size.
Receives the mime types associated with the codec. Use
The actual buffer size needed to retrieve all mime types associated with the codec.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchMimeTypes set to 0 and wzMimeTypes set to
Retrieves a comma delimited list of the file name extensions associated with the codec.
-The size of the file name extension buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of file name extensions associated with the codec. Use
The actual buffer size needed to retrieve all file name extensions associated with the codec.
If this method succeeds, it returns
The default extension for an image encoder is the first item in the list of returned extensions.
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchFileExtensions set to 0 and wzFileExtensions set to
Retrieves a value indicating whether the codec supports animation.
-Receives TRUE if the codec supports images with timing information; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports chromakeys.
-Receives TRUE if the codec supports chromakeys; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports lossless formats.
-Receives TRUE if the codec supports lossless formats; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports multi frame images.
-Receives TRUE if the codec supports multi frame images; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the given mime type matches the mime type of the codec.
-The mime type to compare.
Receives TRUE if the mime types match; otherwise,
Retrieves the container
Retrieves a value indicating whether the codec supports animation.
-Retrieves a value indicating whether the codec supports chromakeys.
-Retrieves a value indicating whether the codec supports lossless formats.
-Retrieves a value indicating whether the codec supports multi frame images.
-Registers a progress notification callback function.
-A function reference to the application defined progress notification callback function. See ProgressNotificationCallback for the callback signature.
A reference to component data for the callback method.
The
If this method succeeds, it returns
Applications can only register a single callback. Subsequent registration calls will replace the previously registered callback. To unregister a callback, pass in
Progress is reported in an increasing order between 0.0 and 1.0. If dwProgressFlags includes
Exposes methods that represent a decoder.
The interface provides access to the decoder's properties such as global thumbnails (if supported), frames, and palette.
-There are a number of concrete implemenations of this interface representing each of the standard decoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), icon (ICO), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native decoder.
| CLSID Name | CLSID |
|---|---|
| 0x6b462062, 0x7cbf, 0x400d, 0x9f, 0xdb, 0x81, 0x3d, 0xd1, 0xf, 0x27, 0x78 | |
| 0x389ea17b, 0x5078, 0x4cde, 0xb6, 0xef, 0x25, 0xc1, 0x51, 0x75, 0xc7, 0x51 | |
| 0xc61bfcdf, 0x2e0f, 0x4aad, 0xa8, 0xd7, 0xe0, 0x6b, 0xaf, 0xeb, 0xcd, 0xfe | |
| 0x9456a480, 0xe88b, 0x43ea, 0x9e, 0x73, 0xb, 0x2d, 0x9b, 0x71, 0xb1, 0xca | |
| 0x381dda3c, 0x9ce9, 0x4834, 0xa2, 0x3e, 0x1f, 0x98, 0xf8, 0xfc, 0x52, 0xbe | |
| 0xb54e85d9, 0xfe23, 0x499f, 0x8b, 0x88, 0x6a, 0xce, 0xa7, 0x13, 0x75, 0x2b | |
| 0xa26cec36, 0x234c, 0x4950, 0xae, 0x16, 0xe3, 0x4a, 0xac, 0xe7, 0x1d, 0x0d |
?
This interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
Codecs written as TIFF container formats that are not register will decode as a TIFF image. Client applications should check for a zero frame count to determine if the codec is valid.
-Retrieves the capabilities of the decoder based on the specified stream.
-The stream to retrieve the decoder capabilities from.
The
Custom decoder implementations should save the current position of the specified
Initializes the decoder with the provided stream.
-The stream to use for initialization.
The stream contains the encoded pixels which are decoded each time the CopyPixels method on the
The
If this method succeeds, it returns
Retrieves the image's container format.
-A reference that receives the image's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Copies the decoder's
If this method succeeds, it returns
CopyPalette returns a global palette (a palette that applies to all the frames in the image) if there is one; otherwise, it returns
Retrieves the metadata query reader from the decoder.
-Receives a reference to the decoder's
If this method succeeds, it returns
Retrieves a preview image, if supported.
-Receives a reference to the preview bitmap if supported.
If this method succeeds, it returns
Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a bitmap thumbnail of the image, if one exists
-Receives a reference to the
If this method succeeds, it returns
None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-A reference that receives the total number of frames in the image.
If this method succeeds, it returns
Retrieves the specified frame of the image.
-The particular frame to retrieve.
A reference that receives a reference to the
Retrieves the image's container format.
-Retrieves an
Retrieves the metadata query reader from the decoder.
-Retrieves a preview image, if supported.
-Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves a bitmap thumbnail of the image, if one exists
-None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-Exposes methods that provide information about a decoder.
-Retrieves the file pattern signatures supported by the decoder.
-The array size of the pPatterns array.
Receives a list of
Receives the number of patterns the decoder supports.
Receives the actual buffer size needed to retrieve all pattern signatures supported by the decoder.
If this method succeeds, it returns
To retrieve all pattern signatures, this method should first be called with pPatterns set to
Retrieves a value that indicates whether the codec recognizes the pattern within a specified stream.
-The stream to pattern match within.
A reference that receives TRUE if the patterns match; otherwise,
Creates a new
If this method succeeds, it returns
Defines methods for setting an encoder's properties such as thumbnails, frames, and palettes.
-There are a number of concrete implemenations of this interface representing each of the standard encoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native encoder.
| CLSID Name | CLSID |
|---|---|
| 0x69be8bb4, 0xd66d, 0x47c8, 0x86, 0x5a, 0xed, 0x15, 0x89, 0x43, 0x37, 0x82 | |
| 0x27949969, 0x876a, 0x41d7, 0x94, 0x47, 0x56, 0x8f, 0x6a, 0x35, 0xa4, 0xdc | |
| 0x1a34f5c1, 0x4a5a, 0x46dc, 0xb6, 0x44, 0x1f, 0x45, 0x67, 0xe7, 0xa6, 0x76 | |
| 0x114f5598, 0xb22, 0x40a0, 0x86, 0xa1, 0xc8, 0x3e, 0xa4, 0x95, 0xad, 0xbd | |
| 0x0131be10, 0x2001, 0x4c5f, 0xa9, 0xb0, 0xcc, 0x88, 0xfa, 0xb6, 0x4c, 0xe8 | |
| 0xac4ce3cb, 0xe1c1, 0x44cd, 0x82, 0x15, 0x5a, 0x16, 0x65, 0x50, 0x9e, 0xc2 |
?
Additionally this interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
-Initializes the encoder with an
If this method succeeds, it returns
Retrieves the encoder's container format.
-A reference that receives the encoder's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the global palette for the image.
-The
Returns
Returns
Sets the global thumbnail for the image.
-The
Returns
Returns
Sets the global preview for the image.
-The
Returns
Returns
Creates a new
If this method succeeds, it returns
The parameter ppIEncoderOptions can be used to receive an
Note??Do not pass in a reference to an initialized
Otherwise, you can pass
See Encoding Overview for an example of how to set encoder options.
-Commits all changes for the image and closes the stream.
-If this method succeeds, it returns
To finalize an image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Retrieves a metadata query writer for the encoder.
-When this method returns, contains a reference to the encoder's metadata query writer.
If this method succeeds, it returns
Retrieves the encoder's container format.
-Retrieves an
Sets the global palette for the image.
-Sets the global thumbnail for the image.
-Sets the global preview for the image.
-Retrieves a metadata query writer for the encoder.
-Exposes methods that provide information about an encoder.
-Creates a new
If this method succeeds, it returns
Exposes methods that produce a flipped (horizontal or vertical) and/or rotated (by 90 degree increments) bitmap source. Rotations are done before the flip.
-IWICBitmapFipRotator requests data on a per-pixel basis, while WIC codecs provide data on a per-scanline basis. This causes the fliprotator object to exhibit n2 behavior if there is no buffering. This occures because each pixel in the transformed image requires an entire scanline to be decoded in the file. It is recommended that you buffer the image using
Initializes the bitmap flip rotator with the provided parameters.
-The input bitmap source.
The
If this method succeeds, it returns
Defines methods for decoding individual image frames of an encoded file.
-Retrieves a metadata query reader for the frame.
-When this method returns, contains a reference to the frame's metadata query reader.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a small preview of the frame, if supported by the codec.
-A reference that receives a reference to the
If this method succeeds, it returns
Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Retrieves a metadata query reader for the frame.
-Retrieves a small preview of the frame, if supported by the codec.
-Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Represents an encoder's individual image frames.
-Initializes the frame encoder using the given properties.
-The set of properties to use for
If this method succeeds, it returns
Sets the output image dimensions for the frame.
-The width of the output image.
The height of the output image.
If this method succeeds, it returns
Sets the physical resolution of the output image.
-The horizontal resolution value.
The vertical resolution value.
If this method succeeds, it returns
Requests that the encoder use the specified pixel format.
-If the method succeeds, contains the specified pixel format
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The |
?
Sets a given number
If this method succeeds, it returns
Sets a given number
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-The bitmap source to use as the thumbnail.
Returns
Returns
SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
The size of the pixel buffer.
A reference to the pixel buffer.
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The value of lineCount is larger than the number of scan lines in the image. |
?
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If this method succeeds, it returns
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Commits the frame to the image.
-If this method succeeds, it returns
To finalize the image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Gets the metadata query writer for the encoder frame.
-When this method returns, contains a reference to metadata query writer for the encoder frame.
If this method succeeds, it returns
Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
A reference to the pixel buffer.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Sets the
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Gets the metadata query writer for the encoder frame.
-Exposes methods that support the Lock method.
-The bitmap lock is simply an abstraction for a rectangular memory window into the bitmap. For the simplest case, a system memory bitmap, this is simply a reference to the top left corner of the rectangle and a stride value.
To release the exclusive lock set by Lock method and the associated
Retrieves the width and height, in pixels, of the locked rectangle.
-A reference that receives the width of the locked rectangle.
A reference that receives the height of the locked rectangle.
If this method succeeds, it returns
Provides access to the stride value for the memory.
-If this method succeeds, it returns
Note the stride value is specific to the
Gets the reference to the top left pixel in the locked rectangle.
-A reference that receives the size of the buffer.
A reference that receives a reference to the top left pixel in the locked rectangle.
The reference provided by this method should not be used outside of the lifetime of the lock itself.
GetDataPointer is not available in multi-threaded apartment applications.
-Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-A reference that receives the pixel format
If this method succeeds, it returns
Provides access to the stride value for the memory.
- Note the stride value is specific to the
Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-Represents a resized version of the input bitmap using a resampling or filtering algorithm.
-Images can be scaled to larger sizes; however, even with sophisticated scaling algorithms, there is only so much information in the image and artifacts tend to worsen the more you scale up.
The scaler will reapply the resampling algorithm every time CopyPixels is called. If the scaled image is to be animated, the scaled image should be created once and cached in a new bitmap, after which the
The scaler is optimized to use the minimum amount of memory required to scale the image correctly. The scaler may be used to produce parts of the image incrementally (banding) by calling CopyPixels with different rectangles representing the output bands of the image. Resampling typically requires overlapping rectangles from the source image and thus may need to request the same pixels from the source bitmap multiple times. Requesting scanlines out-of-order from some image decoders can have a significant performance penalty. Because of this reason, the scaler is optimized to handle consecutive horizontal bands of scanlines (rectangle width equal to the bitmap width). In this case the accumulator from the previous vertically adjacent rectangle is re-used to avoid duplicate scanline requests from the source. This implies that banded output from the scaler may have better performance if the bands are requested sequentially. Of course if the scaler is simply used to produce a single rectangle output, this concern is eliminated because the scaler will internally request scanlines in the correct order.
-Initializes the bitmap scaler with the provided parameters.
-The input bitmap source.
The destination width.
The desination height.
The
If this method succeeds, it returns
Copies pixel data using the supplied input parameters.
-The rectangle of pixels to copy.
The width to scale the source bitmap. This parameter must equal the value obtainable through
The height to scale the source bitmap. This parameter must equal the value obtainable through
The
This
The desired rotation or flip to perform prior to the pixel copy.
The transform must be an operation supported by an DoesSupportTransform call.
If a dstTransform is specified, nStride is the transformed stride and is based on the pguidDstFormat pixel format, not the original source's pixel format.
The stride of the destination buffer.
The size of the destination buffer.
The output buffer.
If this method succeeds, it returns
For codec developer implementation details for this method, see Implementing
When multiple transform operations are requested, the result is dependent on the order in which the operations are performed. To ensure predictability and consistency across CODECs, it's important that all CODECs perform these operations in the same order. The recommended order of these operations is:
Pixel format conversion can be performed at any time, since it has no effect on the other transforms.
The first parameter, prc is used to specify the region of interest for clipping the image. By convention, scaling is performed before clipping so, if the image is to be scaled as well as clipped, the region of interest should be determined after the image has been scaled.
If a dstTransform is specified, the stride is the transformed stride, and is based on the pixelFormat specified in the CopyPixels call, not the original frame's pixel format.
-Returns the closest dimensions the implementation can natively scale to given the desired dimensions.
-The desired width. A reference that receives the closest supported width.
The desired height.A reference that receives the closest supported height.
If this method succeeds, it returns
Retrieves the closest pixel format to which the implementation of
If this method succeeds, it returns
Determines whether a specific transform option is supported natively by the implementation of the
If this method succeeds, it returns
Exposes methods for color management.
-A Color Context is an abstraction for a color profile. The profile can be loaded from a file (ie. "sRGB Color Space Profile.icm") or from a memory buffer obtained by reading. The color profile directory can be obtained by calling the GetColorDirectory API (See http://msdn.microsoft.com/library/en-us/icm/icm_58xl.asp).
-Initializes the color context from the given file.
-If this method succeeds, it returns
Initializes the color context from a memory block.
-The buffer used to initialize the
The size of the pbBuffer buffer.
If this method succeeds, it returns
Initializes the color context using an Exchangeable Image File (EXIF) color space.
-The value of the EXIF color space.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
?
If this method succeeds, it returns
Retrieves the color context type.
-A reference that receives the
If this method succeeds, it returns
Retrieves the color context profile.
-The size of the pbBuffer buffer.
A reference that receives the color context profile.
A reference that receives the actual buffer size needed to retrieve the entire color context profile.
If this method succeeds, it returns
Retrieves the Exchangeable Image File (EXIF) color space color context.
-A reference that receives the EXIF color space color context.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
| Unused. |
?
If this method succeeds, it returns
Retrieves the color context type.
-Retrieves the Exchangeable Image File (EXIF) color space color context.
-Exposes methods that transforms an
A
Initializes an
If this method succeeds, it returns
Exposes methods that provide access to the capabilites of a raw codec format.
-Retrieves information about which capabilities are supported for a raw image.
-A reference that receives
If this method succeeds, it returns
It is recommended that a codec report that a capability is supported even if the results at the outer range limits are not of perfect quality.
-Sets the desired
If this method succeeds, it returns
Gets the current set of parameters.
-A reference that receives a reference to the current set of parameters.
If this method succeeds, it returns
Sets the exposure compensation stop value.
-The exposure compensation value. The value range for exposure compensation is -5.0 through +5.0, which equates to 10 full stops.
If this method succeeds, it returns
It is recommended that a codec report that this method is supported even if the results at the outer range limits are not of perfect quality.
-Gets the exposure compensation stop value of the raw image.
-A reference that receives the exposure compensation stop value. The default is the "as-shot" setting.
If this method succeeds, it returns
Sets the white point RGB values.
-The red white point value.
The green white point value.
The blue white point value.
If this method succeeds, it returns
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the white point RGB values.
-A reference that receives the red white point value.
A reference that receives the green white point value.
A reference that receives the blue white point value.
If this method succeeds, it returns
Sets the named white point of the raw file.
-A bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in the API.
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the named white point of the raw image.
-A reference that receives the bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Sets the white point Kelvin value.
-The white point Kelvin value. Acceptable Kelvin values are 1,500 through 30,000.
If this method succeeds, it returns
Codec implementers should faithfully adjust the color temperature within the range supported natively by the raw image. For values outside the native support range, the codec implementer should provide a best effort representation of the image at that color temperature.
Codec implementers should return
Codec implementers must ensure proper interoperability with other white point setting methods such as SetWhitePointRGB. For example, if the caller sets the white point via SetNamedWhitePoint then the codec implementer may want to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wants to deny a given action because of previous calls,
Gets the white point Kelvin temperature of the raw image.
-A reference that receives the white point Kelvin temperature of the raw image. The default is the "as-shot" setting value.
If this method succeeds, it returns
Gets the information about the current Kelvin range of the raw image.
-A reference that receives the minimum Kelvin temperature.
A reference that receives the maximum Kelvin temperature.
A reference that receives the Kelvin step value.
If this method succeeds, it returns
Sets the contrast value of the raw image.
-The contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the contrast value of the raw image.
-A reference that receives the contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
Sets the desired gamma value.
-The desired gamma value.
If this method succeeds, it returns
Gets the current gamma setting of the raw image.
-A reference that receives the current gamma setting.
If this method succeeds, it returns
Sets the sharpness value of the raw image.
-The sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the sharpness value of the raw image.
-A reference that receives the sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
Sets the saturation value of the raw image.
-The saturation value of the raw image. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the saturation value of the raw image.
-A reference that receives the saturation value of the raw image. The default value is the "as-shot" setting. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
Sets the tint value of the raw image.
-The tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
The codec implementer must determine what the outer range values represent and must determine how to map the values to their image processing routines.
-Gets the tint value of the raw image.
-A reference that receives the tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
Sets the noise reduction value of the raw image.
-The noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents highest noise reduction amount that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the noise reduction value of the raw image.
-A reference that receives the noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents full highest noise reduction amount that can be applied.
If this method succeeds, it returns
Sets the destination color context.
-The destination color context.
If this method succeeds, it returns
Sets the tone curve for the raw image.
-The size of the pToneCurve structure.
The desired tone curve.
If this method succeeds, it returns
Gets the tone curve of the raw image.
-The size of the pToneCurve buffer.
A reference that receives the
A reference that receives the size needed to obtain the tone curve structure.
If this method succeeds, it returns
Sets the desired rotation angle.
-The desired rotation angle.
If this method succeeds, it returns
Gets the current rotation angle.
-A reference that receives the current rotation angle.
If this method succeeds, it returns
Sets the current
If this method succeeds, it returns
Gets the current
If this method succeeds, it returns
Sets the notification callback method.
-Pointer to the notification callback method.
If this method succeeds, it returns
Gets the current set of parameters.
-Gets or sets the exposure compensation stop value of the raw image.
-Gets or sets the named white point of the raw image.
-If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Gets or sets the white point Kelvin temperature of the raw image.
-Gets or sets the contrast value of the raw image.
-Gets or sets the current gamma setting of the raw image.
-Gets or sets the sharpness value of the raw image.
-Gets or sets the saturation value of the raw image.
-Gets or sets the tint value of the raw image.
-Gets or sets the noise reduction value of the raw image.
-Sets the destination color context.
-Gets or sets the current rotation angle.
-Gets or sets the current
Sets the notification callback method.
-Flags used to by
An application-defined callback method used for raw image parameter change notifications.
-A set of
If this method succeeds, it returns
Exposes methods that provide enumeration services for individual metadata items.
-Skips to given number of objects.
-The number of objects to skip.
If this method succeeds, it returns
Resets the current position to the beginning of the enumeration.
-If this method succeeds, it returns
Creates a copy of the current
If this method succeeds, it returns
Exposes methods used for in-place metadata editing. A fast metadata encoder enables you to add and remove metadata to an image without having to fully re-encode the image.
- A decoder must be created using the
Not all metadata formats support fast metadata encoding. The native metadata handlers that support metadata are IFD, Exif, XMP, and GPS.
If a fast metadata encoder fails, the image will need to be fully re-encoded to add the metadata.
-Finalizes metadata changes to the image stream.
-If this method succeeds, it returns
If the commit fails and returns
If the commit fails for any reason, you will need to re-encode the image to ensure the new metadata is added to the image.
-Retrieves a metadata query writer for fast metadata encoding.
-When this method returns, contains a reference to the fast metadata encoder's metadata query writer.
If this method succeeds, it returns
Retrieves a metadata query writer for fast metadata encoding.
- Represents an
Initializes the format converter.
-The input bitmap to convert
The destination pixel format
The
The palette to use for conversion.
The alpha threshold to use for conversion.
The palette translation type to use for conversion.
If this method succeeds, it returns
If you do not have a predefined palette, you must first create one. Use InitializeFromBitmap to create the palette object, then pass it in along with your other parameters.
dither, pIPalette, alphaThresholdPercent, and paletteTranslate are used to mitigate color loss when converting to a reduced bit-depth format. For conversions that do not need these settings, the following parameters values should be used: dither set to
The basic algorithm involved when using an ordered dither requires a fixed palette, found in the
If colors in pIPalette do not closely match those in paletteTranslate, the mapping may produce undesireable results.
When converting a bitmap which has an alpha channel, such as a Portable Network Graphics (PNG), to 8bpp, the alpha channel is normally ignored. Any pixels which were transparent in the original bitmap show up as black in the final output because both transparent and black have pixel values of zero in the respective formats.
Some 8bpp content can contains an alpha color; for instance, the Graphics Interchange Format (GIF) format allows for a single palette entry to be used as a transparent color. For this type of content, alphaThresholdPercent specifies what percentage of transparency should map to the transparent color. Because the alpha value is directly proportional to the opacity (not transparency) of a pixel, the alphaThresholdPercent indicates what level of opacity is mapped to the fully transparent color. For instance, 9.8% implies that any pixel with an alpha value of less than 25 will be mapped to the transparent color. A value of 100% maps all pixels which are not fully opaque to the transparent color. Note that the palette should provide a transparent color. If it does not, the 'transparent' color will be the one closest to zero - often black.
-Determines if the source pixel format can be converted to the destination pixel format.
-The source pixel format.
The destionation pixel format.
A reference that receives a value indicating whether the source pixel format can be converted to the destination pixel format.
Exposes methods that provide information about a pixel format converter.
-Retrieves a list of GUIDs that signify which pixel formats the converter supports.
-The size of the pPixelFormatGUIDs array.
Pointer to a
The actual array size needed to retrieve all pixel formats supported by the converter.
If this method succeeds, it returns
The format converter does not necessarily guarantee symmetricality with respect to conversion; that is, a converter may be able to convert FROM a particular format without actually being able to convert TO a particular format. In order to test symmetricality, use CanConvert.
To determine the number of pixel formats a coverter can handle, set cFormats to 0 and pPixelFormatGUIDs to
Creates a new
If this method succeeds, it returns
Exposes methods used to create components for the Windows Imaging Component (WIC) such as decoders, encoders and pixel format converters.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
When a decoder is created using this method, the file handle must remain alive during the lifetime of the decoder.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Other values may be available for both guidContainerFormat and pguidVendor depending on the installed WIC-enabled encoders. The values listed are those that are natively supported by the operating system.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Component types must be enumerated seperately. Combinations of component types and
Creates a new instance of the fast metadata encoder based on the given
If this method succeeds, it returns
The native image formats provided by Windows Imaging Component (WIC) do not support metadata at the decoder level. WIC codecs only support metadata on image frames. To create a fast metadata encoder from an image frame, see the image factory's CreateFastMetadataEncoderFromFrameDecode method.
-Creates a new instance of the fast metadata encoder based on the given image frame.
-The
When this method returns, contains a reference to a new fast metadata encoder.
If this method succeeds, it returns
Creates a new instance of a query writer.
-The
The
When this method returns, contains a reference to a new
If this method succeeds, it returns
Creates a new instance of a query writer based on the given query reader. The query writer will be pre-populated with metadata from the query reader.
-The
The
When this method returns, contains a reference to a new metadata writer.
If this method succeeds, it returns
Exposes methods for retrieving metadata blocks and items from a decoder or its image frames using a metadata query expression.
-A metadata query reader uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Gets the metadata query readers container format.
-Pointer that receives the cointainer format
If this method succeeds, it returns
Retrieves the current path relative to the root metadata block.
-The length of the wzNamespace buffer.
Pointer that receives the current namespace location.
The actual buffer length that was needed to retrieve the current namespace location.
If this method succeeds, it returns
If the query reader is relative to the top of the metadata hierarchy it will return an empty string.
If the query reader is relative to a nested metadata block this method will return the path to the current query reader.
-Retrieves the metadata block or item identified by a metadata query expression.
-The query expression to the requested metadata block or item.
When this method returns, contains the metadata block or item requested.
If this method succeeds, it returns
GetMetadataByName uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If multiple blocks or items exist that are expressed by the same query expression, the first metadata block or item found will be returned.
-Gets an enumerator of all metadata items at the current relative location within the metadata hierachy.
-When this method returns, contais a reference to an enumerator that contains the metadata items.
If a metadata item is a nested metadata block it will be passed back as a VT_UNKNOWN; otherwise, the "name" of the property will be passed back as a VT_LPWSTR. The enumerator does not enumerate content within nested metadata blocks.
Gets the metadata query readers container format.
-Exposes methods for setting or removing metadata blocks and items to an encoder or its image frames using a metadata query expression.
-A metadata query writer uses metadata query expressions to set or remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Sets a metadata item to a specific location.
-The name of the metadata item.
The metadata to set.
If this method succeeds, it returns
SetMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the value set is a nested metadata block then use variant type VT_UNKNOWN and pvarValue pointing to the
Removes a metadata item from a specific location using a metadata query expression.
-The name of the metadata item to remove.
If this method succeeds, it returns
RemoveMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the metadata item is a metadata block, it is removed from the metadata hierarchy.
-Exposes methods for accessing and building a color table, primarily for indexed pixel formats.
-If the
InitializeFromBitmap's fAddTransparentColor parameter will add a transparent color to the end of the color collection if its size if less than 256, otherwise index 255 will be replaced with the transparent color. If a pre-defined palette type is used, it will change to BitmapPaletteTypeCustom since it no longer matches the predefined palette.
The palette interface is an auxiliary imaging interface in that it does not directly concern bitmaps and pixels; rather it provides indexed color translation for indexed bitmaps. For an indexed pixel format with M bits per pixels: (The number of colors in the palette) greater than 2^M.
Traditionally the basic operation of the palette is to provide a translation from a byte (or smaller) index into a 32bpp color value. This is often accomplished by a 256 entry table of color values.
-Initializes the palette to one of the pre-defined palettes specified by
If this method succeeds, it returns
Initializes a palette to the custom color entries provided.
-Pointer to the color array.
The number of colors in pColors.
If this method succeeds, it returns
If a transparent color is required, it should be provided as part of the custom entries.
The entry count is limited to 256.
-Initializes a palette using a computed optimized values based on the reference bitmap.
-Pointer to the source bitmap.
The number of colors to initialize the palette with.
A value to indicate whether to add a transparent color.
If this method succeeds, it returns
The resulting palette contains the specified number of colors which best represent the colors present in the bitmap. The algorithm operates on the opaque RGB color value of each pixel in the reference bitmap and hence ignores any alpha values. If a transparent color is required, set the fAddTransparentColor parameter to TRUE and one fewer optimized color will be computed, reducing the colorCount, and a fully transparent color entry will be added.
-Initialize the palette based on a given palette.
-Pointer to the source palette.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Pointer that receives the number of colors in the color table.
If this method succeeds, it returns
Fills out the supplied color array with the colors from the internal color table. The color array should be sized according to the return results from GetColorCount.
-If this method succeeds, it returns
Retrieves a value that describes whether the palette is black and white.
-Pointer that receives TRUE if the palette is black and white; otherwise,
If this method succeeds, it returns
Retrieves a value that describes whether a palette is grayscale.
-Pointer that receives TRUE if the palette is grayscale; otherwise
If this method succeeds, it returns
Retrieves a value that describes whether the palette contains an alpha transparent color.
-Pointer that receives TRUE if the palette contains a transparent color; otherwise,
If this method succeeds, it returns
Retrieves the
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Retrieves a value that describes whether the palette is black and white.
-Retrieves a value that describes whether a palette is grayscale.
-Exposes methods that provide information about a pixel format.
-Gets the pixel format
Pointer that receives the pixel format
If this method succeeds, it returns
Gets the pixel format's
If this method succeeds, it returns
Gets the bits per pixel (BPP) of the pixel format.
-Pointer that receives the BPP of the pixel format.
If this method succeeds, it returns
Gets the number of channels the pixel format contains.
-Pointer that receives the channel count.
If this method succeeds, it returns
Gets the pixel format's channel mask.
-The index to the channel mask to retrieve.
The size of the pbMaskBuffer buffer.
Pointer to the mask buffer.
The actual buffer size needed to obtain the channel mask.
If this method succeeds, it returns
Gets the pixel format
Gets the pixel format's
Gets the bits per pixel (BPP) of the pixel format.
-Gets the number of channels the pixel format contains.
-Extends
Returns whether the format supports transparent pixels.
-Returns TRUE if the pixel format supports transparency; otherwise, false.
If this method succeeds, it returns
Returns the
If this method succeeds, it returns
Returns whether the format supports transparent pixels.
-Notify method is documented only for compliance; its use is not recommended and may be altered or unavailable in the future. Instead, and use RegisterProgressNotification. -
-If this method succeeds, it returns
Exposes methods for obtaining information about and controlling progressive decoding.
-Images can only be progressively decoded if they were progressively encoded. The native encoders supplied by Windows Imaging Component (WIC) do not
E_NOTIMPL is returned if the codec does not support progressive level decoding.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Indicates the number of levels supported by the CODEC.
If this method succeeds, it returns
Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets the last level set by the SetCurrentLevel call.
-If this method succeeds, it returns
Specifies the level to retrieve on the next call to CopyPixels.
-If this method succeeds, it returns
A call does not have to request every level supported. If a caller requests level 1, without having previously requested level 0, the bits returned by the next call to CopyPixels will include both levels.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets or sets the last level set by the SetCurrentLevel call.
-Represents a Windows Imaging Component (WIC) stream for referencing imaging and metadata content.
-Decoders and metadata handlers are expected to create sub streams of whatever stream they hold when handing off control for embedded metadata to another metadata handler. If the stream is not restricted then use MAXLONGLONG as the max size and offset 0.
The
Initializes a stream from another stream. Access rights are inherited from the underlying stream.
-The initialize stream.
If this method succeeds, it returns
Initializes a stream from a particular file.
-The file used to initialize the stream.
The desired file access mode.
| Value | Meaning |
|---|---|
| Read access. |
| Write access. |
?
If this method succeeds, it returns
The
Initializes a stream to treat a block of memory as a stream. The stream cannot grow beyond the buffer size.
-Pointer to the buffer used to initialize the stream.
The size of buffer.
If this method succeeds, it returns
This method should be avoided whenever possible. The caller is responsible for ensuring the memory block is valid for the lifetime of the stream when using InitializeFromMemory. A workaround for this behavior is to create an
If you require a growable memory stream, use CreateStreamOnHGlobal.
-Initializes the stream as a substream of another stream.
-Pointer to the input stream.
The stream offset used to create the new stream.
The maximum size of the stream.
If this method succeeds, it returns
The stream functions with its own stream position, independent of the underlying stream but restricted to a region. All seek positions are relative to the sub region. It is allowed, though not recommended, to have multiple writable sub streams overlapping the same range.
-Contains members that identify a pattern within an image file which can be used to identify a particular format.
-The offset the pattern is located in the file.
The pattern length.
The actual pattern.
The pattern mask.
The end of the stream.
Defines raw codec capabilites.
-Size of the
The codec's major version.
The codec's minor version.
The
The
The
The
The
The
The
The
The
The
The
The
The
The
The
Represents a raw image tone curve.
-The number of tone curve points.
The array of tone curve points.
Represents a raw image tone curve point.
-The tone curve input.
The tone curve output.
Represents an object that can receive drawing commands. Interfaces that inherit from
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Represents a Direct2D drawing resource.
-Retrieves the factory associated with this resource.
-When this method returns, contains a reference to a reference to the factory that created this resource. This parameter is passed uninitialized.
Retrieves the factory associated with this resource.
-Creates a Direct2D bitmap from a reference to in-memory source data.
-The dimension of the bitmap to create in pixels.
A reference to the memory location of the image data, or
The byte count of each scanline, which is equal to (the image width in pixels ? the number of bytes per pixel) + memory padding. If srcData is
The pixel format and dots per inch (DPI) of the bitmap to create.
When this method returns, contains a reference to a reference to the new bitmap. This parameter is passed uninitialized.
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Before Direct2D can load a WIC bitmap, that bitmap must be converted to a supported pixel format and alpha mode. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.
-Creates an
If this method succeeds, it returns
The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.
Sharing anBy passing an
You may also use this method to reinterpret the data of an existing bitmap and specify a new DPI or alpha mode. For example, in the case of a bitmap atlas, an
When using a DXGI surface render target (an
Note also that the
For more information about interoperability with Direct3D, see the Direct2D and Direct3D Interoperability Overview.
Sharing anAn
To use an
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a layer resource that can be used with this render target and its compatible render targets.
-When the method returns, contains a reference to a reference to the new layer. This parameter is passed uninitialized.
If this method succeeds, it returns
The layer automatically resizes itself, as needed.
-Create a mesh that uses triangles to describe a shape.
-When this method returns, contains a reference to a reference to the new mesh.
If this method succeeds, it returns
To populate a mesh, use its Open method to obtain an
Draws a line between the specified points using the specified stroke style.
-The start point of the line, in device-independent pixels.
The end point of the line, in device-independent pixels.
The brush used to paint the line's stroke.
A value greater than or equal to 0.0f that specifies the width of the stroke. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.
The style of stroke to paint, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the
Draws the outline of a rectangle that has the specified dimensions and stroke style.
-The dimensions of the rectangle to draw, in device-independent pixels.
The brush used to paint the rectangle's stroke.
A value greater than or equal to 0.0f that specifies the width of the rectangle's stroke. The stroke is centered on the rectangle's outline.
The style of stroke to paint, or
When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the
Paints the interior of the specified rectangle.
-The dimension of the rectangle to paint, in device-independent pixels.
The brush used to paint the rectangle's interior.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the
Draws the outline of the specified rounded rectangle using the specified stroke style.
-The dimensions of the rounded rectangle to draw, in device-independent pixels.
The brush used to paint the rounded rectangle's outline.
The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.
The style of the rounded rectangle's stroke, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the
Paints the interior of the specified rounded rectangle.
-The dimensions of the rounded rectangle to paint, in device independent pixels.
The brush used to paint the interior of the rounded rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the
Draws the outline of the specified ellipse using the specified stroke style.
-The position and radius of the ellipse to draw, in device-independent pixels.
The brush used to paint the ellipse's outline.
The thickness of the ellipse's stroke. The stroke is centered on the ellipse's outline.
The style of stroke to apply to the ellipse's outline, or
The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the
Paints the interior of the specified ellipse.
-The position and radius, in device-independent pixels, of the ellipse to paint.
The brush used to paint the interior of the ellipse.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the
Draws the outline of the specified geometry using the specified stroke style.
-The geometry to draw.
The brush used to paint the geometry's stroke.
The thickness of the geometry's stroke. The stroke is centered on the geometry's outline.
The style of stroke to apply to the geometry's outline, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the
Paints the interior of the specified geometry.
-The geometry to paint.
The brush used to paint the geometry's interior.
The opacity mask to apply to the geometry, or
If the opacityBrush parameter is not
When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the
Paints the interior of the specified mesh.
-The mesh to paint.
The brush used to paint the mesh.
The current antialias mode of the render target must be
FillMesh does not expect a particular winding order for the triangles in the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the
For this method to work properly, the render target must be using the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the
Draws the specified bitmap after scaling it to the size of the specified rectangle.
-The bitmap to render.
The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn. If the rectangle is not well-ordered, nothing is drawn, but the render target does not enter an error state.
A value between 0.0f and 1.0f, inclusive, that specifies the opacity value to be applied to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. Default is 1.0f.
The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is
The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to draw;
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the
To draw text with Direct2D, use the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the
Draws the formatted text described by the specified
When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the
Draws the specified glyphs.
-The origin, in device-independent pixels, of the glyphs' baseline.
The glyphs to render.
The brush used to paint the specified glyphs.
A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the
Gets the current transform of the render target.
-When this returns, contains the current transform of the render target. This parameter is passed uninitialized.
Sets the antialiasing mode of the render target. The antialiasing mode applies to all subsequent drawing operations, excluding text and glyph drawing operations.
-The antialiasing mode for future drawing operations.
To specify the antialiasing mode for text and glyph operations, use the SetTextAntialiasMode method.
-Retrieves the current antialiasing mode for nontext drawing operations.
-The current antialiasing mode for nontext drawing operations.
Specifies the antialiasing mode to use for subsequent text and glyph drawing operations.
-The antialiasing mode to use for subsequent text and glyph drawing operations.
Gets the current antialiasing mode for text and glyph drawing operations.
-The current antialiasing mode for text and glyph drawing operations.
Specifies text rendering options to be applied to all subsequent text and glyph drawing operations.
-The text rendering options to be applied to all subsequent text and glyph drawing operations;
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the render target's current text rendering options.
-When this method returns, textRenderingParamscontains the address of a reference to the render target's current text rendering options.
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Specifies a label for subsequent drawing operations.
-A label to apply to subsequent drawing operations.
A label to apply to subsequent drawing operations.
The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.
-Gets the label for subsequent drawing operations.
-When this method returns, contains the first label for subsequent drawing operations. This parameter is passed uninitialized. If
When this method returns, contains the second label for subsequent drawing operations. This parameter is passed uninitialized. If
If the same address is passed for both parameters, both parameters receive the value of the second tag.
-Adds the specified layer to the render target so that it receives all subsequent drawing operations until PopLayer is called.
-The PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.
Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.
A particular
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the
Stops redirecting drawing operations to the layer that is specified by the last PushLayer call.
-A PopLayer must match a previous PushLayer call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the
Executes all pending drawing commands.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
This command does not flush the device that is associated with the render target.
Calling this method resets the error state of the render target.
-Saves the current drawing state to the specified
Sets the render target's drawing state to that of the specified
Specifies a rectangle to which all subsequent drawing operations are clipped.
-The size and position of the clipping area, in device-independent pixels.
The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.
The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.
The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.
Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.
Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.
After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.
The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.
Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.
The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.
A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the
Removes the last axis-aligned clip from the render target. After this method is called, the clip is no longer applied to subsequent drawing operations.
-A PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.
PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.
For an example, see How to Clip with an Axis-Aligned Clip Rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the
Clears the drawing area to the specified color.
-The color to which the drawing area is cleared.
Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is
If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.
-Initiates drawing on this render target.
-Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Ends drawing operations on the render target and indicates the current error state and associated tags.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Retrieves the pixel format and alpha mode of the render target.
-The pixel format and alpha mode of the render target.
Sets the dots per inch (DPI) of the render target.
-A value greater than or equal to zero that specifies the horizontal DPI of the render target.
A value greater than or equal to zero that specifies the vertical DPI of the render target.
This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed.
For
Return the render target's dots per inch (DPI).
-When this method returns, contains the horizontal DPI of the render target. This parameter is passed uninitialized.
When this method returns, contains the vertical DPI of the render target. This parameter is passed uninitialized.
This method indicates the mapping from pixel space to device-independent space for the render target.
For
Returns the size of the render target in device-independent pixels.
-The current size of the render target in device-independent pixels.
Returns the size of the render target in device pixels.
-The size of the render target in device pixels.
Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-The maximum size, in pixels, of any one bitmap dimension supported by the render target.
Indicates whether the render target supports the specified properties.
-The render target properties to test.
TRUE if the specified render target properties are supported by this render target; otherwise,
This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.
-Gets or sets the current transform of the render target.
-Retrieves or sets the current antialiasing mode for nontext drawing operations.
-Gets or sets the current antialiasing mode for text and glyph drawing operations.
-Retrieves or sets the render target's current text rendering options.
-If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the pixel format and alpha mode of the render target.
-Returns the size of the render target in device-independent pixels.
-Returns the size of the render target in device pixels.
-Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
-You create an
if (SUCCEEDED(hr))
- { hr = g_pGdiInterop->CreateBitmapRenderTarget(hdc, r.right, r.bottom, &g_pBitmapRenderTarget);
- }
-
One way to use a
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, DWRITE_MEASURING_MODE measuringMode, __in DWRITE_GLYPH_RUN const* glyphRun, __in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription, IUnknown* clientDrawingEffect )
- { HRESULT hr = S_OK; // Pass on the drawing call to the render target to do the real work. RECT dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;
- }
-
- The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not. Default rendering params can be retrieved by using the Draws a run of glyphs to a bitmap target at the specified position.
-The horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The measuring method for glyphs in the run, used with the other properties to determine the rendering mode.
The structure containing the properties of the glyph run.
The object that controls rendering behavior.
The foreground color of the text.
The optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.
If this method succeeds, it returns
You can use the
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not.
Default rendering params can be retrieved by using the
Gets a handle to the memory device context.
-Returns a device context handle to the memory device context.
An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets the number of bitmap pixels per DIP.
-The number of bitmap pixels per DIP.
A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Sets the number of bitmap pixels per DIP (device-independent pixel). A DIP is 1/96 inch, so this value is the number if pixels per inch divided by 96.
-A value that specifies the number of pixels per DIP.
If this method succeeds, it returns
Gets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-When this method returns, contains a transform matrix.
If this method succeeds, it returns
Sets the transform that maps abstract coordinate to DIPs (device-independent pixel). This does not affect the world transform of the underlying device context.
- Specifies the new transform. This parameter can be
If this method succeeds, it returns
Gets the dimensions of the target bitmap.
-Returns the width and height of the bitmap in pixels.
If this method succeeds, it returns
Resizes the bitmap.
-The new bitmap width, in pixels.
The new bitmap height, in pixels.
If this method succeeds, it returns
Gets a handle to the memory device context.
- An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets or sets the number of bitmap pixels per DIP.
-A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Gets or sets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-Gets the dimensions of the target bitmap.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
- The application implemented rendering callback (
If this method succeeds, it returns
If this method succeeds, it returns
TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object. In the case of a simple bitmap, with no padding and no overhang, all the overhangs will simply be zeroes.
The overhangs should be returned relative to the reported size of the object (see
If this method succeeds, it returns
Layout uses this to determine the line-breaking behavior of the inline object among the text.
-When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately preceding it.
When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately following it.
If this method succeeds, it returns
Used to create all subsequent DirectWrite objects. This interface is the root factory interface for all DirectWrite objects.
- Create an
if (SUCCEEDED(hr))
- { hr = An
Gets an object which represents the set of installed fonts.
-If this parameter is nonzero, the function performs an immediate check for changes to the set of installed fonts. If this parameter is
When this method returns, contains the address of a reference to the system font collection object, or
Creates a font collection using a custom font collection loader.
-An application-defined font collection loader, which must have been previously registered using RegisterFontCollectionLoader.
The key used by the loader to identify a collection of font files. The buffer allocated for this key should at least be the size of collectionKeySize.
The size, in bytes, of the collection key.
Contains an address of a reference to the system font collection object if the method succeeds, or
If this method succeeds, it returns
Registers a custom font collection loader with the factory object.
-Pointer to a
If this method succeeds, it returns
This function registers a font collection loader with DirectWrite. The font collection loader interface, which should be implemented by a singleton object, handles enumerating font files in a font collection given a particular type of key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
-If this method succeeds, it returns
Creates a font file reference object from a local font file.
-An array of characters that contains the absolute file path for the font file. Subsequent operations on the constructed object may fail if the user provided filePath doesn't correspond to a valid file on the disk.
The last modified time of the input file path. If the parameter is omitted, the function will access the font file to obtain its last write time. You should specify this value to avoid extra disk access. Subsequent operations on the constructed object may fail if the user provided lastWriteTime doesn't match the file on the disk.
When this method returns, contains an address of a reference to the newly created font file reference object, or
If this method succeeds, it returns
Creates a reference to an application-specific font file resource.
-A font file reference key that uniquely identifies the font file resource during the lifetime of fontFileLoader.
The size of the font file reference key in bytes.
The font file loader that will be used by the font system to load data from the file identified by fontFileReferenceKey.
Contains an address of a reference to the newly created font file object when this method succeeds, or
If this method succeeds, it returns
This function is provided for cases when an application or a document needs to use a private font without having to install it on the system. fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
-Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates a rendering parameters object with default settings for the primary monitor. Different monitors may have different rendering parameters, for more information see the How to Add Support for Multiple Monitors topic.
-Standard
Creates a rendering parameters object with default settings for the specified monitor. In most cases, this is the preferred way to create a rendering parameters object.
-A handle for the specified monitor.
When this method returns, contains an address of a reference to the rendering parameters object created by this method.
If this method succeeds, it returns
Creates a rendering parameters object with the specified properties.
-The gamma level to be set for the new rendering parameters object.
The enhanced contrast level to be set for the new rendering parameters object.
The ClearType level to be set for the new rendering parameters object.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.
A value that represents the method (for example, ClearType natural quality) for rendering glyphs.
When this method returns, contains an address of a reference to the newly created rendering parameters object.
If this method succeeds, it returns
Registers a font file loader with DirectWrite.
-Pointer to a
If this method succeeds, it returns
This function registers a font file loader with DirectWrite. The font file loader interface, which should be implemented by a singleton object, handles loading font file resources of a particular type from a key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
-If this method succeeds, it returns
This function unregisters font file loader callbacks with the DirectWrite font system. You should implement the font file loader interface by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite should be performed outside of the font file loader implementation.
-Creates a text format object used for text layout.
-An array of characters that contains the name of the font family
A reference to a font collection object. When this is
A value that indicates the font weight for the text object created by this method.
A value that indicates the font style for the text object created by this method.
A value that indicates the font stretch for the text object created by this method.
The logical size of the font in DIP ("device-independent pixel") units. A DIP equals 1/96 inch.
An array of characters that contains the locale name.
When this method returns, contains an address of a reference to a newly created text format object, or
If this method succeeds, it returns
Creates a typography object for use in a text layout.
-When this method returns, contains the address of a reference to a newly created typography object, or
If this method succeeds, it returns
Creates an object that is used for interoperability with GDI.
-When this method returns, contains an address of a reference to a GDI interop object if successful, or
If this method succeeds, it returns
Takes a string, text format, and associated constraints, and produces an object that represents the fully analyzed and formatted result.
-An array of characters that contains the string to create a new
The number of characters in the string.
A reference to an object that indicates the format to apply to the string.
The width of the layout box.
The height of the layout box.
When this method returns, contains an address of a reference to the resultant text layout object.
If this method succeeds, it returns
Takes a string, format, and associated constraints, and produces an object representing the result, formatted for a particular display resolution and measuring mode.
-An array of characters that contains the string to create a new
The length of the string, in character count.
The text formatting object to apply to the string.
The width of the layout box.
The height of the layout box.
The number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI device pixelsPerDip is 1. If rendering onto a 120 DPI device pixelsPerDip is 1.25 (120/96).
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specifies the font size and pixels per DIP.
Instructs the text layout to use the same metrics as GDI bi-level text when set to
When this method returns, contains an address to the reference of the resultant text layout object.
If this method succeeds, it returns
The resulting text layout should only be used for the intended resolution, and for cases where text scalability is desired CreateTextLayout should be used instead.
-Creates an inline object for trimming, using an ellipsis as the omission sign.
-A text format object, created with CreateTextFormat, used for text layout.
When this method returns, contains an address of a reference to the omission (that is, ellipsis trimming) sign created by this method.
If this method succeeds, it returns
The ellipsis will be created using the current settings of the format, including base font, style, and any effects. Alternate omission signs can be created by the application by implementing
Returns an interface for performing text analysis.
-When this method returns, contains an address of a reference to the newly created text analyzer object.
If this method succeeds, it returns
Creates a number substitution object using a locale name, substitution method, and an indicator whether to ignore user overrides (use NLS defaults for the given culture instead).
-A value that specifies how to apply number substitution on digits and related punctuation.
The name of the locale to be used in the numberSubstitution object.
A Boolean flag that indicates whether to ignore user overrides.
When this method returns, contains an address to a reference to the number substitution object created by this method.
If this method succeeds, it returns
Creates a glyph run analysis object, which encapsulates information used to render a glyph run.
-A structure that contains the properties of the glyph run (font face, advances, and so on).
Number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI bitmap then pixelsPerDip is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 1.25.
Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified the emSize and pixelsPerDip.
A value that specifies the rendering mode, which must be one of the raster rendering modes (that is, not default and not outline).
Specifies the measuring mode to use with glyphs.
The horizontal position (X-coordinate) of the baseline origin, in DIPs.
Vertical position (Y-coordinate) of the baseline origin, in DIPs.
When this method returns, contains an address of a reference to the newly created glyph run analysis object.
If this method succeeds, it returns
The glyph run analysis object contains the results of analyzing the glyph run, including the positions of all the glyphs and references to all of the rasterized glyphs in the font cache.
-Creates an object that is used for interoperability with GDI.
-An object that encapsulates a set of fonts, such as the set of fonts installed on the system, or the set of fonts in a particular directory. The font collection API can be used to discover what font families and fonts are available, and to obtain some metadata about the fonts.
-The
null ; // Get the system font collection.
- if (SUCCEEDED(hr))
- { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection);
- }
-
To determine what fonts are available on the system, get a reference to the system font collection. You can then use the
#include <dwrite.h>
- #include <string.h>
- #include <stdio.h>
- #include <new> // SafeRelease inline function.
- template <class T> inline void SafeRelease(T **ppT)
- { if (*ppT) { (*ppT)->Release(); *ppT = null ; }
- } void wmain()
- { null ; null ; // Get the system font collection. if (SUCCEEDED(hr)) { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection); } UINT32 familyCount = 0; // Get the number of font families in the collection. if (SUCCEEDED(hr)) { familyCount = pFontCollection->GetFontFamilyCount(); } for (UINT32 i = 0; i < familyCount; ++i) { null ; // Get the font family. if (SUCCEEDED(hr)) { hr = pFontCollection->GetFontFamily(i, &pFontFamily); } null ; // Get a list of localized strings for the family name. if (SUCCEEDED(hr)) { hr = pFontFamily->GetFamilyNames(&pFamilyNames); } UINT32 index = 0; null ) { hr = E_OUTOFMEMORY; } // Get the family name. if (SUCCEEDED(hr)) { hr = pFamilyNames->GetString(index, name, length+1); } if (SUCCEEDED(hr)) { // Print out the family name. wprintf(L"%s\n", name); } SafeRelease(&pFontFamily); SafeRelease(&pFamilyNames); delete [] name; } SafeRelease(&pFontCollection); SafeRelease(&pDWriteFactory);
- } Gets the number of font families in the collection.
-The number of font families in the collection.
Creates a font family object given a zero-based font family index.
-Zero-based index of the font family.
When this method returns, contains the address of a reference to the newly created font family object.
Finds the font family with the specified family name.
-An array of characters, which is null-terminated, containing the name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.
When this method returns, contains the zero-based index of the matching font family if the family name was found; otherwise, UINT_MAX.
When this method returns, TRUE if the family name exists; otherwise,
Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong to the font collection.
-A font face object that specifies the physical font.
When this method returns, contains the address of a reference to the newly created font object if successful; otherwise,
Gets the number of font families in the collection.
-Used to construct a collection of fonts given a particular type of key.
-The font collection loader interface is recommended to be implemented by a singleton object. Note that font collection loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Represents an absolute reference to a font face which contains font face type, appropriate file references, face identification data and various font data such as metrics, names and glyph outlines.
-Obtains the file format type of a font face.
-A value that indicates the type of format for the font face (such as Type 1, TrueType, vector, or bitmap).
Obtains the font files representing a font face.
-If fontFiles is
When this method returns, contains a reference to a user-provided array that stores references to font files representing the font face. This parameter can be
If this method succeeds, it returns
The
Then, call the method a second time, passing the numberOfFiles value that was output the first call, and a non-null buffer of the correct size to store the
Obtains the index of a font face in the context of its font files.
-The zero-based index of a font face in cases when the font files contain a collection of font faces. If the font files contain a single face, this value is zero.
Obtains the algorithmic style simulation flags of a font face.
-Font face simulation flags for algorithmic means of making text bold or italic.
Determines whether the font is a symbol font.
-Returns TRUE if the font is a symbol font, otherwise
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, a?
Obtains the number of glyphs in the font face.
-The number of glyphs in the font face.
Obtains ideal (resolution-independent) glyph metrics in font design units.
-An array of glyph indices for which to compute metrics. The array must contain at least as many elements as specified by glyphCount.
The number of elements in the glyphIndices array.
When this method returns, contains an array of
Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation
If this method succeeds, it returns
Design glyph metrics are used for glyph positioning.
-Returns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.
-An array of USC4 code points from which to obtain nominal glyph indices. The array must be allocated and be able to contain the number of elements specified by codePointCount.
The number of elements in the codePoints array.
When this method returns, contains a reference to an array of nominal glyph indices filled by this function.
If this method succeeds, it returns
Note that this mapping is primarily provided for line layout engines built on top of the physical font API. Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond to how a Unicode string will map to glyph indices when rendering using a particular font face. Also, note that Unicode variant selectors provide for alternate mappings for character to glyph. This call will always return the default variant.
- Finds the specified OpenType font table if it exists and returns a reference to it. The function accesses the underlying font data through the
If this method succeeds, it returns
The context for the same tag may be different for each call, so each one must be held and released separately.
-Releases the table obtained earlier from TryGetFontTable.
-Computes the outline of a run of glyphs by calling back to the outline sink interface.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
An array of glyph indices. The glyphs are in logical order and the advance direction depends on the isRightToLeft parameter. The array must be allocated and be able to contain the number of elements specified by glyphCount.
An optional array of glyph advances in DIPs. The advance of a glyph is the amount to advance the position (in the direction of the baseline) after drawing the glyph. glyphAdvances contains the number of elements specified by glyphCount.
An optional array of glyph offsets, each of which specifies the offset along the baseline and offset perpendicular to the baseline of a glyph relative to the current pen position. glyphOffsets contains the number of elements specified by glyphCount.
The number of glyphs in the run.
If TRUE, the ascender of the glyph runs alongside the baseline. If
A client can render a vertical run by setting isSideways to TRUE and rotating the resulting geometry 90 degrees to the right using a transform. The isSideways and isRightToLeft parameters cannot both be true.
The visual order of the glyphs. If this parameter is
A reference to the interface that is called back to perform outline drawing operations.
If this method succeeds, it returns
Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
The number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:
A reference to an object that contains rendering settings such as gamma level, enhanced contrast, and ClearType level. This parameter is necessary in case the rendering parameters object overrides the rendering mode.
When this method returns, contains a value that indicates the recommended rendering mode to use.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
-The logical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
A reference to a DWRITE_FONT_METRICS structure to fill in. The metrics returned by this function are in font design units.
Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.
-The ogical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
When set to
An array of glyph indices for which to compute the metrics.
The number of elements in the glyphIndices array.
An array of
A
Standard
Obtains the file format type of a font face.
-Obtains the index of a font face in the context of its font files.
-Obtains the algorithmic style simulation flags of a font face.
-Determines whether the font is a symbol font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Obtains the number of glyphs in the font face.
-Specifies properties used to identify and execute typographic features in the current font face.
-A non-zero value generally enables the feature execution, while the zero value disables it. A feature requiring a selector uses this value to indicate the selector index.
The OpenType standard provides access to typographic features available in the font by means of a feature tag with the associated parameters. The OpenType feature tag is a 4-byte identifier of the registered name of a feature. For example, the 'kern' feature name tag is used to identify the 'Kerning' feature in OpenType font. Similarly, the OpenType feature tag for 'Standard Ligatures' and 'Fractions' is 'liga' and 'frac' respectively. Since a single run can be associated with more than one typographic features, the Text String API accepts typographic settings for a run as a list of features and are executed in the order they are specified.
The value of the tag member represents the OpenType name tag of the feature, while the param value represents additional parameter for the execution of the feature referred by the tag member. Both nameTag and parameter are stored as little endian, the same convention followed by GDI. Most features treat the Param value as a binary value that indicates whether to turn the execution of the feature on or off, with it being off by default in the majority of cases. Some features, however, treat this value as an integral value representing the integer index to the list of alternate results it may produce during the execution; for instance, the feature 'Stylistic Alternates' or 'salt' uses the parameter value as an index to the list of alternate substituting glyphs it could produce for a specified glyph.
-The feature OpenType name identifier.
The execution parameter of the feature.
Represents a font file. Applications such as font managers or font viewers can call
Obtains the reference to the reference key of a font file. The returned reference is valid until the font file object is released.
-When this method returns, contains an address of a reference to the font file reference key. Note that the reference value is only valid until the font file object it is obtained from is released. This parameter is passed uninitialized.
When this method returns, contains the size of the font file reference key in bytes. This parameter is passed uninitialized.
If this method succeeds, it returns
Obtains the file loader associated with a font file object.
-When this method returns, contains the address of a reference to the font file loader associated with the font file object.
If this method succeeds, it returns
Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
-TRUE if the font type is supported by the font system; otherwise,
When this method returns, contains a value that indicates the type of the font file. Note that even if isSupportedFontType is
When this method returns, contains a value that indicates the type of the font face. If fontFileType is not equal to
When this method returns, contains the number of font faces contained in the font file.
If this method succeeds, it returns
Important??Certain font file types are recognized, but not supported by the font system. For example, the font system will recognize a file as a Type 1 font file but will not be able to construct a font face object from it. In such situations, Analyze will set isSupportedFontType output parameter to
Encapsulates a collection of font files. The font system uses this interface to enumerate font files when building a font collection.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Creates a font file stream object that encapsulates an open file resource.
-A reference to a font file reference key that uniquely identifies the font file resource within the scope of the font loader being used. The buffer allocated for this key must at least be the size, in bytes, specified by fontFileReferenceKeySize.
The size of font file reference key, in bytes.
When this method returns, contains the address of a reference to the newly created
If this method succeeds, it returns
The resource is closed when the last reference to fontFileStream is released.
-Loads font file data from a custom font file loader.
-Loads font file data from a custom font file loader.
-Reads a fragment from a font file.
-When this method returns, contains an address of a reference to the start of the font file fragment. This parameter is passed uninitialized.
The offset of the fragment, in bytes, from the beginning of the font file.
The size of the file fragment, in bytes.
When this method returns, contains the address of a reference to a reference to the client-defined context to be passed to ReleaseFileFragment.
If this method succeeds, it returns
Note that ReadFileFragment implementations must check whether the requested font file fragment is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
DirectWrite may invoke
Releases a fragment from a file.
-A reference to the client-defined context of a font fragment returned from ReadFileFragment.
Obtains the total size of a file.
-When this method returns, contains the total size of the file.
If this method succeeds, it returns
Implementing GetFileSize() for asynchronously loaded font files may require downloading the complete file contents. Therefore, this method should be used only for operations that either require a complete font file to be loaded (for example, copying a font file) or that need to make decisions based on the value of the file size (for example, validation against a persisted file size).
-Obtains the last modified time of the file.
-When this method returns, contains the last modified time of the file in the format that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC).
If this method succeeds, it returns
The "last modified time" is used by DirectWrite font selection algorithms to determine whether one font resource is more up to date than another one.
-Provides interoperability with GDI, such as methods to convert a font face to a
Creates a font object that matches the properties specified by the
A structure containing a GDI-compatible font description.
When this method returns, contains an address of a reference to a newly created
If this method succeeds, it returns
Initializes a
An
When this method returns, contains a structure that receives a GDI-compatible font description.
When this method returns, contains TRUE if the specified font object is part of the system font collection; otherwise,
If this method succeeds, it returns
The conversion to a
Initializes a
An
When this method returns, contains a reference to a structure that receives a GDI-compatible font description.
If this method succeeds, it returns
The conversion to a
Creates an
A handle to a device context into which a font has been selected. It is assumed that the client has already performed font mapping and that the font selected into the device context is the actual font to be used for rendering glyphs.
Contains an address of a reference to the newly created font face object, or
This function is intended for scenarios in which an application wants to use GDI and Uniscribe 1.x for text layout and shaping, but DirectWrite for final rendering. This function assumes the client is performing text output using glyph indexes.
-Creates an object that encapsulates a bitmap and memory DC (device context) which can be used for rendering glyphs.
-A handle to the optional device context used to create a compatible memory DC (device context).
The width of the bitmap render target.
The height of the bitmap render target.
When this method returns, contains an address of a reference to the newly created
Contains the information needed by renderers to draw glyph runs. All coordinates are in device independent pixels (DIPs).
-The physical font face object to draw with.
The logical size of the font in DIPs (equals 1/96 inch), not points.
The number of glyphs in the glyph run.
A reference to an array of indices to render for the glyph run.
A reference to an array containing glyph advance widths for the glyph run.
A reference to an array containing glyph offsets for the glyph run.
If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used. Vertical writing is achieved by specifying isSideways = true and rotating the entire run 90 degrees to the right via a rotate transform.
The implicit resolved bidi level of the run. Odd levels indicate right-to-left languages like Hebrew and Arabic, while even levels indicate left-to-right languages like English and Japanese (when written horizontally). For right-to-left languages, the text origin is on the right, and text should be drawn to the left.
Contains low-level information used to render a glyph run.
-The alpha texture can be a bi-level alpha texture or a ClearType alpha texture.
A bi-level alpha texture contains one byte per pixel, therefore the size of the buffer for a bi-level texture will be the area of the texture bounds, in bytes. Each byte in a bi-level alpha texture created by CreateAlphaTexture is either set to DWRITE_ALPHA_MAX (that is, 255) or zero.
A ClearType alpha texture contains three bytes per pixel, therefore the size of the buffer for a ClearType alpha texture is three times the area of the texture bounds, in bytes.
-Gets the bounding rectangle of the physical pixels affected by the glyph run.
-Specifies the type of texture requested. If a bi-level texture is requested, the bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only antialiased glyphs.
When this method returns, contains the bounding rectangle of the physical pixels affected by the glyph run, or an empty rectangle if there are no glyphs of the specified texture type.
Creates an alpha texture of the specified type for glyphs within a specified bounding rectangle.
-A value that specifies the type of texture requested. This can be DWRITE_TEXTURE_BILEVEL_1x1 or
The bounding rectangle of the texture, which can be different than the bounding rectangle returned by GetAlphaTextureBounds.
When this method returns, contains the array of alpha values from the texture. The buffer allocated for this array must be at least the size of bufferSize.
The size of the alphaValues array, in bytes. The minimum size depends on the dimensions of the rectangle and the type of texture requested.
If this method succeeds, it returns
Gets alpha blending properties required for ClearType blending.
-An object that specifies the ClearType level and enhanced contrast, gamma, pixel geometry, and rendering mode. In most cases, the values returned by the output parameters of this method are based on the properties of this object, unless a GDI-compatible rendering mode was specified.
When this method returns, contains the gamma value to use for gamma correction.
When this method returns, contains the enhanced contrast value to be used for blending.
When this method returns, contains the ClearType level used in the alpha blending.
If this method succeeds, it returns
Contains additional properties related to those in
An array of characters containing the locale name associated with this run.
An array of characters containing the text associated with the glyphs.
The number of characters in UTF16 code-units. Note that this may be different than the number of glyphs.
An array of indices to the glyph indices array, of the first glyphs of all the glyph clusters of the glyphs to render.
Corresponding text position in the string this glyph run came from. This is relative to the beginning of the string represented by the
Line breakpoint characteristics of a character.
-Indicates a breaking condition before the character.
Indicates a breaking condition after the character.
Indicates that the character is some form of whitespace, which may be meaningful for justification.
Indicates that the character is a soft hyphen, often used to indicate hyphenation points inside words.
Reserved for future use.
Represents a collection of strings indexed by locale name.
-The set of strings represented by an
A common use for the
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-The number of language/string pairs.
Gets the zero-based index of the locale name/string pair with the specified locale name.
-A null-terminated array of characters containing the locale name to look for.
The zero-based index of the locale name/string pair. This method initializes index to UINT_MAX.
When this method returns, contains TRUE if the locale name exists; otherwise,
Note that if the locale name does not exist, the return value is a success and the exists parameter is
UINT32 index = 0;
- Gets the length in characters (not including the null terminator) of the locale name with the specified index.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains the length in characters of the locale name, not including the null terminator.
If this method succeeds, it returns
Copies the locale name with the specified index to the specified array.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains a character array, which is null-terminated, that receives the locale name from the language/string pair. The buffer allocated for this array must be at least the size of size, in element count.
The size of the array in characters. The size must include space for the terminating null character.
If this method succeeds, it returns
Gets the length in characters (not including the null terminator) of the string with the specified index.
-A zero-based index of the language/string pair.
The length in characters of the string, not including the null terminator, from the language/string pair.
If this method succeeds, it returns
Use GetStringLength to get the string length before calling the
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Copies the string with the specified index to the specified array.
-The zero-based index of the language/string pair to be examined.
The null terminated array of characters that receives the string from the language/string pair. The buffer allocated for this array should be at least the size of size. GetStringLength can be used to get the size of the array before using this method.
The size of the array in characters. The size must include space for the terminating null character. GetStringLength can be used to get the size of the array before using this method.
If this method succeeds, it returns
The string returned must be allocated by the caller. You can get the size of the string by using the GetStringLength method prior to calling GetString, as shown in the following example.
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-Holds the appropriate digits and numeric punctuation for a specified locale.
-Defines the pixel snapping properties such as pixels per DIP(device-independent pixel) and the current transform matrix of a text renderer.
-Represents text rendering settings such as ClearType level, enhanced contrast, and gamma correction for glyph rasterization and filtering.
An application typically obtains a rendering parameters object by calling the
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-Returns the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Returns the amount of contrast enhancement. Valid values are greater than or equal to zero.
Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level of the rendering parameters object.
The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-A value that indicates the type of pixel geometry used in the rendering parameters object.
Gets the rendering mode of the rendering parameters object.
-A value that indicates the rendering mode of the rendering parameters object.
By default, the rendering mode is initialized to
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-Gets the rendering mode of the rendering parameters object.
-By default, the rendering mode is initialized to
Contains shaping output properties for an output glyph.
-Indicates that the glyph has justification applied.
Indicates that the glyph is the start of a cluster.
Indicates that the glyph is a diacritic mark.
Indicates that the glyph is a word boundary with no visible space.
Reserved for future use.
This interface is implemented by the text analyzer's client to receive the output of a given text analysis.
-The text analyzer disregards any current state of the analysis sink, therefore, a Set method call on a range overwrites the previously set analysis result of the same range.
-Implemented by the text analyzer's client to provide text to the analyzer. It allows the separation between the logical view of text as a continuous stream of characters identifiable by unique text positions, and the actual memory layout of potentially discrete blocks of text in the client's backing store.
-If any of these callbacks returns an error, then the analysis functions will stop prematurely and return a callback error. Note that rather than return E_NOTIMPL, an application should stub the method and return a constant/null and
Analyzes various text properties for complex script processing such as bidirectional (bidi) support for languages like Arabic, determination of line break opportunities, glyph placement, and number substitution.
-Analyzes a text range for script boundaries, reading text attributes from the source and reporting the Unicode script ID to the sink callback SetScript.
-If this method succeeds, it returns
Analyzes a text range for script directionality, reading attributes from the source and reporting levels to the sink callback SetBidiLevel.
-If this method succeeds, it returns
While the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs. Otherwise, the returned levels may be wrong, because the Bidi algorithm is meant to apply to the paragraph as a whole.
-Analyzes a text range for spans where number substitution is applicable, reading attributes from the source and reporting substitutable ranges to the sink callback SetNumberSubstitution.
-If this method succeeds, it returns
Although the function can handle multiple ranges of differing number substitutions, the text ranges should not arbitrarily split the middle of numbers. Otherwise, it will treat the numbers separately and will not translate any intervening punctuation.
-Analyzes a text range for potential breakpoint opportunities, reading attributes from the source and reporting breakpoint opportunities to the sink callback SetLineBreakpoints.
-If this method succeeds, it returns
Although the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs, unless the specified text span is considered a whole unit. Otherwise, the returned properties for the first and last characters will inappropriately allow breaks.
-Parses the input text string and maps it to the set of glyphs and associated glyph data according to the font and the writing system's rendering rules.
-An array of characters to convert to glyphs.
The length of textString.
The font face that is the source of the output glyphs.
A Boolean flag set to TRUE if the text is intended to be drawn vertically.
A Boolean flag set to TRUE for right-to-left text.
A reference to a Script analysis result from an AnalyzeScript call.
The locale to use when selecting glyphs. For example the same character may map to different glyphs for ja-jp versus zh-chs. If this is
A reference to an optional number substitution which selects the appropriate glyphs for digits and related numeric characters, depending on the results obtained from AnalyzeNumberSubstitution. Passing
An array of references to the sets of typographic features to use in each feature range.
The length of each feature range, in characters. The sum of all lengths should be equal to textLength.
The number of feature ranges.
The maximum number of glyphs that can be returned.
When this method returns, contains the mapping from character ranges to glyph ranges.
When this method returns, contains a reference to an array of structures that contains shaping properties for each character.
The output glyph indices.
When this method returns, contains a reference to an array of structures that contain shaping properties for each output glyph.
When this method returns, contains the actual number of glyphs returned if the call succeeds.
If this method succeeds, it returns
Note that the mapping from characters to glyphs is, in general, many-to-many. The recommended estimate for the per-glyph output buffers is (3 * textLength / 2 + 16). This is not guaranteed to be sufficient. The value of the actualGlyphCount parameter is only valid if the call succeeds. In the event that maxGlyphCount is not big enough, HRESULT_FROM_WIN32(
Places glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
Place glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
The
To get a reference to the
if (SUCCEEDED(hr))
- { hr = pDWriteFactory_->CreateTextFormat( L"Gabriola", null , When creating an
These properties cannot be changed after the
The
To draw text with multiple formats, or to use a custom text renderer, use the
This object may not be thread-safe, and it may carry the state of text format change.
DirectWrite and Direct2D To draw simple text with a single format, Direct2D provides the
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the alignment of text in a paragraph, relative to the leading and trailing edge of a layout box for a
This method can return one of the following values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| The textAlignment argument is invalid. |
?
The text can be aligned to the leading or trailing edge of the layout box, or it can be centered. The following illustration shows text with the alignment set to
Note??The alignment is dependent on reading direction, the above is for left-to-right reading direction. For right-to-left reading direction it would be the opposite.
See
Sets the alignment option of a paragraph relative to the layout box's top and bottom edge.
-The paragraph alignment option being set for a paragraph; see
If this method succeeds, it returns
Sets the word wrapping option.
-The word wrapping option being set for a paragraph; see
If this method succeeds, it returns
Sets the paragraph reading direction.
-The text reading direction (for example,
If this method succeeds, it returns
Sets the paragraph flow direction.
-The paragraph flow direction; see
If this method succeeds, it returns
Sets a fixed distance between two adjacent tab stops.
-The fixed distance between two adjacent tab stops.
If this method succeeds, it returns
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the line spacing.
-Specifies how line height is being determined; see
The line height, or distance between one baseline to another.
The distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
For the default method, spacing depends solely on the content. For uniform spacing, the specified line height overrides the content.
-Gets the alignment option of text relative to the layout box's leading and trailing edge.
-Returns the text alignment option of the current paragraph.
Gets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-A value that indicates the current paragraph alignment option.
Gets the word wrapping option.
-Returns the word wrapping option; see
Gets the current reading direction for text in a paragraph.
-A value that indicates the current reading direction for text in a paragraph.
Gets the direction that text lines flow.
-The direction that text lines flow within their parent container. For example,
Gets the incremental tab stop position.
-The incremental tab stop value.
Gets the trimming options for text that overflows the layout box.
-When this method returns, it contains a reference to a
When this method returns, contains an address of a reference to a trimming omission sign. This parameter may be
If this method succeeds, it returns
Gets the line spacing adjustment set for a multiline text paragraph.
-A value that indicates how line height is determined.
When this method returns, contains the line height, or distance between one baseline to another.
When this method returns, contains the distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
Gets the current font collection.
-When this method returns, contains an address of a reference to the font collection being used for the current text.
If this method succeeds, it returns
Gets the length of the font family name.
-The size of the character array, in character count, not including the terminated
Gets a copy of the font family name.
-When this method returns, contains a reference to a character array, which is null-terminated, that receives the current font family name. The buffer allocated for this array should be at least the size, in elements, of nameSize.
The size of the fontFamilyName character array, in character count, including the terminated
If this method succeeds, it returns
Gets the font weight of the text.
-A value that indicates the type of weight (such as normal, bold, or black).
Gets the font style of the text.
-A value which indicates the type of font style (such as slope or incline).
Gets the font stretch of the text.
-A value which indicates the type of font stretch (such as normal or condensed).
Gets the font size in DIP unites.
-The current font size in DIP units.
Gets the length of the locale name.
-The size of the character array in character count, not including the terminated
Gets a copy of the locale name.
-Contains a character array that receives the current locale name.
The size of the character array, in character count, including the terminated
If this method succeeds, it returns
Gets or sets the alignment option of text relative to the layout box's leading and trailing edge.
-Gets or sets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-Gets or sets the word wrapping option.
-Gets or sets the current reading direction for text in a paragraph.
-Gets or sets the direction that text lines flow.
-Gets or sets the incremental tab stop position.
-Gets the current font collection.
-Gets the font weight of the text.
-Gets the font style of the text.
-Gets the font stretch of the text.
-Gets the font size in DIP unites.
-The
To get a reference to the
// Create a text layout using the text format.
- if (SUCCEEDED(hr))
- { The
// Set the font weight to bold for the first 5 letters.
- To draw the block of text represented by an
To draw a formatted string represented by an
To render using a custom renderer, use the
// Draw the text layout using DirectWrite and the CustomTextRenderer class.
- hr = pTextLayout_->Draw( null , pTextRenderer_, // Custom text renderer. origin.x, origin.y );
Using a custom text renderer also enables you to render using another technology, such as GDI.
-Sets the layout maximum width.
-A value that indicates the maximum width of the layout box.
If this method succeeds, it returns
Sets the layout maximum height.
-A value that indicates the maximum height of the layout box.
If this method succeeds, it returns
Sets the font collection.
-The font collection to set.
Text range to which this change applies.
If this method succeeds, it returns
Sets null-terminated font family name for text within a specified text range.
-The font family name that applies to the entire text string within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font weight for text within a text range specified by a
If this method succeeds, it returns
The font weight can be set to one of the predefined font weight values provided in the
The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
- Sets the font style for text within a text range specified by a
If this method succeeds, it returns
The font style can be set to Normal, Italic or Oblique. The following illustration shows three styles for the Palatino font. For more information, see
Sets the font stretch for text within a specified text range.
-A value which indicates the type of font stretch for text within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font size in DIP units for text within a specified text range.
-The font size in DIP units to be set for text in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets underlining for text within a specified text range.
-A Boolean flag that indicates whether underline takes place within a specified text range.
Text range to which this change applies.
If this method succeeds, it returns
Sets strikethrough for text within a specified text range.
-A Boolean flag that indicates whether strikethrough takes place in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the application-defined drawing effect.
-Application-defined drawing effects that apply to the range. This data object will be passed back to the application's drawing callbacks for final rendering.
The text range to which this change applies.
If this method succeeds, it returns
An
This drawing effect is associated with the specified range and will be passed back to the application by way of the callback when the range is drawn at drawing time.
-Sets the inline object.
-An application-defined inline object.
Text range to which this change applies.
If this method succeeds, it returns
The application may call this function to specify the set of properties describing an application-defined inline object for specific range.
This inline object applies to the specified range and will be passed back to the application by way of the DrawInlineObject callback when the range is drawn. Any text in that range will be suppressed.
-Sets font typography features for text within a specified text range.
-Pointer to font typography settings.
Text range to which this change applies.
If this method succeeds, it returns
Sets the locale name for text within a specified text range.
-A null-terminated locale name string.
Text range to which this change applies.
If this method succeeds, it returns
Gets the layout maximum width.
-Returns the layout maximum width.
Gets the layout maximum height.
-The layout maximum height.
Gets the font collection associated with the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
Contains an address of a reference to the current font collection.
Get the length of the font family name at the current position.
-The current text position.
When this method returns, contains the size of the character array containing the font family name, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family.
If this method succeeds, it returns
Copies the font family name of the text at the specified position.
-The position of the text to examine.
When this method returns, contains an array of characters that receives the current font family name. You must allocate storage for this parameter.
The size of the character array in character count including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family name.
If this method succeeds, it returns
Gets the font weight of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font weight.
When this method returns, contains a value which indicates the type of font weight being applied at the specified position.
Gets the font style (also known as slope) of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font style.
When this method returns, contains a value which indicates the type of font style (also known as slope or incline) being applied at the specified position.
Gets the font stretch of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font stretch.
When this method returns, contains a value which indicates the type of font stretch (also known as width) being applied at the specified position.
Gets the font em height of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font size.
When this method returns, contains the size of the font in ems of the text at the specified position.
Gets the underline presence of the text at the specified position.
-The current text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
A Boolean flag that indicates whether underline is present at the position indicated by currentPosition.
Get the strikethrough presence of the text at the specified position.
-The position of the text to inspect.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to strikethrough.
A Boolean flag that indicates whether strikethrough is present at the position indicated by currentPosition.
Gets the application-defined drawing effect at the specified text position.
-The position of the text whose drawing effect is to be retrieved.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the drawing effect.
When this method returns, contains an address of a reference to the current application-defined drawing effect. Usually this effect is a foreground brush that is used in glyph drawing.
Gets the inline object at the specified position.
-The specified text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the inline object.
Contains the application-defined inline object.
Gets the typography setting of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the typography.
When this method returns, contains an address of a reference to the current typography setting.
Gets the length of the locale name of the text at the specified position.
-The position of the text to inspect.
Size of the character array, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Gets the locale name of the text at the specified position.
-The position of the text to inspect.
When this method returns, contains the character array receiving the current locale name.
Size of the character array, in character count, including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Draws text using the specified client drawing context.
-An application-defined drawing context.
Pointer to the set of callback functions used to draw parts of a text string.
The x-coordinate of the layout's left side.
The y-coordinate of the layout's top side.
If this method succeeds, it returns
To draw text with this method, a textLayout object needs to be created by the application using
After the textLayout object is obtained, the application calls the
Retrieves the information about each individual text line of the text string.
-When this method returns, contains a reference to an array of structures containing various calculated length values of individual text lines.
The maximum size of the lineMetrics array.
When this method returns, contains the actual size of the lineMetrics array that is needed.
If this method succeeds, it returns
If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Retrieves overall metrics for the formatted string.
-When this method returns, contains the measured distances of text and associated content after being formatted.
If this method succeeds, it returns
Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Overshoots of visible extents (in DIPs) outside the layout.
If this method succeeds, it returns
Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Retrieves logical properties and measurements of each glyph cluster.
-When this method returns, contains metrics, such as line-break or total advance width, for a glyph cluster.
The maximum size of the clusterMetrics array.
When this method returns, contains the actual size of the clusterMetrics array that is needed.
If this method succeeds, it returns
If maxClusterCount is not large enough, then E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
-Minimum width.
The application calls this function passing in a specific pixel location relative to the top-left location of the layout box and obtains the information about the correspondent hit-test metrics of the text string where the hit-test has occurred. When the specified pixel location is outside the text string, the function sets the output value *isInside to
The pixel location X to hit-test, relative to the top-left location of the layout box.
The pixel location Y to hit-test, relative to the top-left location of the layout box.
An output flag that indicates whether the hit-test location is at the leading or the trailing side of the character. When the output *isInside value is set to
An output flag that indicates whether the hit-test location is inside the text string. When
The output geometry fully enclosing the hit-test location. When the output *isInside value is set to
The application calls this function to get the pixel location relative to the top-left of the layout box given the text position and the logical side of the position. This function is normally used as part of caret positioning of text where the caret is drawn at the location corresponding to the current text editing position. It may also be used as a way to programmatically obtain the geometry of a particular text position in UI automation.
-The text position used to get the pixel location.
A Boolean flag that indicates whether the pixel location is of the leading or the trailing side of the specified text position.
When this method returns, contains the output pixel location X, relative to the top-left location of the layout box.
When this method returns, contains the output pixel location Y, relative to the top-left location of the layout box.
When this method returns, contains the output geometry fully enclosing the specified text position.
The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string. The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
The first text position of the specified range.
The number of positions of the specified range.
The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.
The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.
When this method returns, contains a reference to a buffer of the output geometry fully enclosing the specified position range. The buffer must be at least as large as maxHitTestMetricsCount.
Maximum number of boxes hitTestMetrics could hold in its buffer memory.
Actual number of geometries hitTestMetrics holds in its buffer memory.
If this method succeeds, it returns
Gets or sets the layout maximum width.
-Gets or sets the layout maximum height.
-Retrieves overall metrics for the formatted string.
-Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Specifies a range of text positions where format is applied in the text represented by an
Represents a set of application-defined callbacks that perform rendering of text, inline objects, and decorations such as underlines.
-Represents a bitmap that has been bound to an
To create a bitmap, use one of the following methods of the render target on which the bitmap will be drawn:
For information about the pixel formats supported by Direct2D bitmaps, see Supported Pixel Formats and Alpha Modes.
An
Returns the size, in device-independent pixels (DIPs), of the bitmap.
-The size, in DIPs, of the bitmap.
A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-The size, in pixels, of the bitmap.
Retrieves the pixel format and alpha mode of the bitmap.
-The pixel format and alpha mode of the bitmap.
Return the dots per inch (DPI) of the bitmap.
-The horizontal DPI of the image. You must allocate storage for this parameter.
The vertical DPI of the image. You must allocate storage for this parameter.
Copies the specified region from the specified bitmap into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The bitmap to copy from.
The area of bitmap to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Copies the specified region from the specified render target into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The render target that contains the region to copy.
The area of renderTarget to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
All clips and layers must be popped off of the render target before calling this method. The method returns
Copies the specified region from memory into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The data to copy.
The stride, or pitch, of the source bitmap stored in srcData. The stride is the byte count of a scanline (one row of pixels in memory). The stride can be computed from the following formula: pixel width * bytes per pixel + memory padding.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion; the two bitmap formats should match.
If this method is passed invalid input (such as an invalid destination rectangle), can produce unpredictable results, such as a distorted image or device failure.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Returns the size, in device-independent pixels (DIPs), of the bitmap.
-A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-Retrieves the pixel format and alpha mode of the bitmap.
-Paints an area with a bitmap.
-A bitmap brush is used to fill a geometry with a bitmap. Like all brushes, it defines an infinite plane of content. Because bitmaps are finite, the brush relies on an "extend mode" to determine how the plane is filled horizontally and vertically.
CreatingTo create a bitmap brush, use the
An
Defines an object that paints an area. Interfaces that derive from
An
Brush space in Direct2D is specified differently than in XPS and Windows Presentation Foundation (WPF). In Direct2D, brush space is not relative to the object being drawn, but rather is the current coordinate system of the render target, transformed by the brush transform, if present. To paint an object as it would be painted by a WPF brush, you must translate the brush space origin to the upper-left corner of the object's bounding box, and then scale the brush space so that the base tile fills the bounding box of the object.
For more information about brushes, see the Brushes Overview.
-Sets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Sets the transformation applied to the brush.
-The transformation to apply to this brush.
When you paint with a brush, it paints in the coordinate space of the render target. Brushes do not automatically position themselves to align with the object being painted; by default, they begin painting at the origin (0, 0) of the render target.
You can "move" the gradient defined by an
To align the content of an
The following illustrations show the effect of using an
The illustration on the right shows the result of transforming the
Gets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Gets the transform applied to this brush.
-The transform applied to this brush.
When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Gets or sets the degree of opacity of this brush.
-Gets or sets the transform applied to this brush.
-When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Specifies how the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies how the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies the interpolation mode used when the brush bitmap is scaled or rotated.
-The interpolation mode used when the brush bitmap is scaled or rotated.
This method sets the interpolation mode for a bitmap, which is an enum value that is specified in the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, bilinear interpolation positions the bitmap more precisely to the application requests, but blurs the bitmap in the process.
-Specifies the bitmap source that this brush uses to paint.
-The bitmap source used by the brush.
This method specifies the bitmap source that this brush uses to paint. The bitmap is not resized or rescaled automatically to fit the geometry that it fills. The bitmap stays at its native size. To resize or translate the bitmap, use the SetTransform method to apply a transform to the brush.
The native size of a bitmap is the width and height in bitmap pixels, divided by the bitmap DPI. This native size forms the base tile of the brush. To tile a subregion of the bitmap, you must generate a new bitmap containing this subregion and use SetBitmap to apply it to the brush. -
-Gets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Like all brushes,
Gets the method by which the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Like all brushes,
Gets the interpolation method used when the brush bitmap is scaled or rotated.
-The interpolation method used when the brush bitmap is scaled or rotated.
This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets the bitmap source that this brush uses to paint.
-When this method returns, contains the address to a reference to the bitmap with which this brush paints.
Gets or sets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the method by which the brush vertically tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the interpolation method used when the brush bitmap is scaled or rotated.
-This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets or sets the bitmap source that this brush uses to paint.
-Describes the pixel format and dpi of a bitmap.
-The bitmap's pixel format and alpha mode.
The horizontal dpi of the bitmap.
The vertical dpi of the bitmap.
Renders to an intermediate texture created by the CreateCompatibleRenderTarget method.
-An
To write directly to a WIC bitmap instead, use the
To create a bitmap render target, call the
Like other render targets, an
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-When this method returns, contains the address of a reference to the bitmap for this render target. This bitmap can be used for drawing operations.
If this method succeeds, it returns
The DPI for the
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-The DPI for the
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Adds an OpenType font feature.
-A structure that contains the OpenType name identifier and the execution parameter for the font feature being added.
If this method succeeds, it returns
Gets the number of OpenType font features for the current font.
-The number of font features for the current text format.
A single run of text can be associated with more than one typographic feature. The
Gets the font feature at the specified index.
-The zero-based index of the font feature to retrieve.
When this method returns, contains the font feature which is at the specified index.
A single run of text can be associated with more than one typographic feature. The
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Contains the center point, x-radius, and y-radius of an ellipse.
-The center point of the ellipse.
The X-radius of the ellipse.
The Y-radius of the ellipse.
Provides access to an device context that can accept GDI drawing commands.
-You don't create an
Not all render targets support the
Note that the QueryInterface method always succeeds; if the render target doesn't support the
To test whether a given render target supports the
Retrieves the device context associated with this render target.
-A value that specifies whether the device context should be cleared.
When this method returns, contains the device context associated with this render target. You must allocate storage for this parameter.
Calling this method flushes the render target.
This command can be called only after BeginDraw and before EndDraw. It should not be called between PushAxisAlignedClip/PopAxisAlignedClip commands or between PushLayer/PopLayer.
ReleaseDC must be called once for each call to GetDC.
-Indicates that drawing with the device context retrieved using the GetDC method is finished.
-If this method succeeds, it returns
ReleaseDC must be called once for each call to GetDC.
-Indicates the condition at the edges of inline object or text used to determine line-breaking behavior.
-Indicates whether a break is allowed by determining the condition of the neighboring text span or inline object.
Indicates that a line break is allowed, unless overruled by the condition of the neighboring text span or inline object, either prohibited by a "may not break" condition or forced by a "must break" condition.
Indicates that there should be no line break, unless overruled by a "must break" condition from the neighboring text span or inline object.
Indicates that the line break must happen, regardless of the condition of the adjacent text span or inline object.
Specifies the type of DirectWrite factory object.
-A DirectWrite factory object contains information about its internal state, such as font loader registration and cached font data. In most cases you should use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state information, thereby reducing memory usage. However, there are cases when it is desirable to reduce the impact of a component on the rest of the process, such as a plug-in from an untrusted source, by sandboxing and isolating it from the rest of the process components. In such cases, you should use an isolated factory for the sandboxed component.
-Indicates that the DirectWrite factory is a shared factory and that it allows for the reuse of cached font data across multiple in-process components. Such factories also take advantage of cross process font caching components for better performance.
Indicates that the DirectWrite factory object is isolated. Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
Indicates the direction of flow for placing lines of text in a paragraph.
-Specifies that text lines are placed from top to bottom.
Indicates the file format of a complete font face.
-Font formats that consist of multiple files, such as Type 1 .PFM and .PFB, have a single enum entry.
-OpenType font face with CFF outlines.
OpenType font face with TrueType outlines.
OpenType font face that is a part of a TrueType collection.
A Type 1 font face.
A vector .FON format font face.
A bitmap .FON format font face.
Font face type is not recognized by the DirectWrite font system.
A value that indicates the typographic feature of text supplied by the font.
-Replaces figures separated by a slash with an alternative form.
Equivalent OpenType tag: 'afrc'
Turns capital characters into petite capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in petite-cap form to avoid disrupting the flow of text. See the pcap feature description for notes on the relationship of caps, smallcaps and petite caps.
Equivalent OpenType tag: 'c2pc'
Turns capital characters into small capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in small-cap form to avoid disrupting the flow of text.
Equivalent OpenType tag: 'c2sc'
In specified situations, replaces default glyphs with alternate forms which provide better joining behavior. Used in script typefaces which are designed to have some or all of their glyphs join.
Equivalent OpenType tag: 'calt'
Shifts various punctuation marks up to a position that works better with all-capital sequences or sets of lining figures; also changes oldstyle figures to lining figures. By default, glyphs in a text face are designed to work with lowercase characters. Some characters should be shifted vertically to fit the higher visual center of all-capital or lining text. Also, lining figures are the same height (or close to it) as capitals, and fit much better with all-capital text.
Equivalent OpenType tag: 'case'
To minimize the number of glyph alternates, it is sometimes desired to decompose a character into two glyphs. Additionally, it may be preferable to compose two characters into a single glyph for better glyph processing. This feature permits such composition/decomposition. The feature should be processed as the first feature processed, and should be processed only when it is called.
Equivalent OpenType tag: 'ccmp'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. Unlike other ligature features, clig specifies the context in which the ligature is recommended. This capability is important in some script designs and for swash ligatures.
Equivalent OpenType tag: 'clig'
Globally adjusts inter-glyph spacing for all-capital text. Most typefaces contain capitals and lowercase characters, and the capitals are positioned to work with the lowercase. When capitals are used for words, they need more space between them for legibility and esthetics. This feature would not apply to monospaced designs. Of course the user may want to override this behavior in order to do more pronounced letterspacing for esthetic reasons.
Equivalent OpenType tag: 'cpsp'
Replaces default character glyphs with corresponding swash glyphs in a specified context. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'cswh'
In cursive scripts like Arabic, this feature cursively positions adjacent glyphs.
Equivalent OpenType tag: 'curs'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures which may be used for special effect, at the user's preference.
Equivalent OpenType tag: 'dlig'
Replaces standard forms in Japanese fonts with corresponding forms preferred by typographers. For example, a user would invoke this feature to replace kanji character U+5516 with U+555E. -
Equivalent OpenType tag: 'expt'
Replaces figures separated by a slash with 'common' (diagonal) fractions.
Equivalent OpenType tag: 'frac'
Replaces glyphs set on other widths with glyphs set on full (usually em) widths. In a CJKV font, this may include "lower ASCII" Latin characters and various symbols. In a European font, this feature replaces proportionally-spaced glyphs with monospaced glyphs, which are generally set on widths of 0.6 em. For example, a user may invoke this feature in a Japanese font to get full monospaced Latin glyphs instead of the corresponding proportionally-spaced versions.
Equivalent OpenType tag: 'fwid'
Produces the half forms of consonants in Indic scripts. For example, in Hindi (Devanagari script), the conjunct KKa, obtained by doubling the Ka, is denoted with a half form of Ka followed by the full form.
Equivalent OpenType tag: 'half'
Produces the halant forms of consonants in Indic scripts. For example, in Sanskrit (Devanagari script), syllable final consonants are frequently required in their halant form.
Equivalent OpenType tag: 'haln'
Respaces glyphs designed to be set on full-em widths, fitting them onto half-em widths. This differs from hwid in that it does not substitute new glyphs.
Equivalent OpenType tag: 'halt'
Replaces the default (current) forms with the historical alternates. While some ligatures are also used for historical effect, this feature deals only with single characters. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hist'
Replaces standard kana with forms that have been specially designed for only horizontal writing. This is a typographic optimization for improved fit and more even color.
Equivalent OpenType tag: 'hkna'
Replaces the default (current) forms with the historical alternates. Some ligatures were in common use in the past, but appear anachronistic today. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hlig'
Replaces glyphs on proportional widths, or fixed widths other than half an em, with glyphs on half-em (en) widths. Many CJKV fonts have glyphs which are set on multiple widths; this feature selects the half-em version. There are various contexts in which this is the preferred behavior, including compatibility with older desktop documents.
Equivalent OpenType tag: 'hwid'
Used to access the JIS X 0212-1990 glyphs for the cases when the JIS X 0213:2004 form is encoded. The JIS X 0212-1990 (aka, "Hojo Kanji") and JIS X 0213:2004 character sets overlap significantly. In some cases their prototypical glyphs differ. When building fonts that support both JIS X 0212-1990 and JIS X 0213:2004 (such as those supporting the Adobe-Japan 1-6 character collection), it is recommended that JIS X 0213:2004 forms be the preferred encoded form.
Equivalent OpenType tag: 'hojo'
The National Language Council (NLC) of Japan has defined new glyph shapes for a number of JIS characters, which were incorporated into JIS X 0213:2004 as new prototypical forms. The 'jp04' feature is A subset of the 'nlck' feature, and is used to access these prototypical glyphs in a manner that maintains the integrity of JIS X 0213:2004.
Equivalent OpenType tag: 'jp04'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS C 6226-1978 (JIS78) specification.
Equivalent OpenType tag: 'jp78'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS X 0208-1983 (JIS83) specification.
Equivalent OpenType tag: 'jp83'
Replaces Japanese glyphs from the JIS78 or JIS83 specifications with the corresponding forms from the JIS X 0208-1990 (JIS90) specification.
Equivalent OpenType tag: 'jp90'
Adjusts amount of space between glyphs, generally to provide optically consistent spacing between glyphs. Although a well-designed typeface has consistent inter-glyph spacing overall, some glyph combinations require adjustment for improved legibility. Besides standard adjustment in the horizontal direction, this feature can supply size-dependent kerning data via device tables, "cross-stream" kerning in the Y text direction, and adjustment of glyph placement independent of the advance adjustment. Note that this feature may apply to runs of more than two glyphs, and would not be used in monospaced fonts. Also note that this feature does not apply to text set vertically.
Equivalent OpenType tag: 'kern'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers the ligatures which the designer/manufacturer judges should be used in normal conditions.
Equivalent OpenType tag: 'liga'
Changes selected figures from oldstyle to the default lining form. For example, a user may invoke this feature in order to get lining figures, which fit better with all-capital text. This feature overrides results of the Oldstyle Figures feature (onum).
Equivalent OpenType tag: 'lnum'
Enables localized forms of glyphs to be substituted for default forms. Many scripts used to write multiple languages over wide geographical areas have developed localized variant forms of specific letters, which are used by individual literary communities. For example, a number of letters in the Bulgarian and Serbian alphabets have forms distinct from their Russian counterparts and from each other. In some cases the localized form differs only subtly from the script 'norm', in others the forms are radically distinct.
Equivalent OpenType tag: 'locl'
Positions mark glyphs with respect to base glyphs. For example, in Arabic script positioning the Hamza above the Yeh.
Equivalent OpenType tag: 'mark'
Replaces standard typographic forms of Greek glyphs with corresponding forms commonly used in mathematical notation (which are a subset of the Greek alphabet).
Equivalent OpenType tag: 'mgrk'
Positions marks with respect to other marks. Required in various non-Latin scripts like Arabic. For example, in Arabic, the ligaturised mark Ha with Hamza above it can also be obtained by positioning these marks relative to one another.
Equivalent OpenType tag: 'mkmk'
Replaces default glyphs with various notational forms (such as glyphs placed in open or solid circles, squares, parentheses, diamonds or rounded boxes). In some cases an annotation form may already be present, but the user may want a different one.
Equivalent OpenType tag: 'nalt'
Used to access glyphs made from glyph shapes defined by the National Language Council (NLC) of Japan for a number of JIS characters in 2000.
Equivalent OpenType tag: 'nlck'
Changes selected figures from the default lining style to oldstyle form. For example, a user may invoke this feature to get oldstyle figures, which fit better into the flow of normal upper- and lowercase text. This feature overrides results of the Lining Figures feature (lnum).
Equivalent OpenType tag: 'onum'
Replaces default alphabetic glyphs with the corresponding ordinal forms for use after figures. One exception to the follows-a-figure rule is the numero character (U+2116), which is actually a ligature substitution, but is best accessed through this feature.
Equivalent OpenType tag: 'ordn'
Respaces glyphs designed to be set on full-em widths, fitting them onto individual (more or less proportional) horizontal widths. This differs from pwid in that it does not substitute new glyphs (GPOS, not GSUB feature). The user may prefer the monospaced form, or may simply want to ensure that the glyph is well-fit and not rotated in vertical setting (Latin forms designed for proportional spacing would be rotated).
Equivalent OpenType tag: 'palt'
Turns lowercase characters into petite capitals. Forms related to petite capitals, such as specially designed figures, may be included. Some fonts contain an additional size of capital letters, shorter than the regular smallcaps and it is referred to as petite caps. Such forms are most likely to be found in designs with a small lowercase x-height, where they better harmonise with lowercase text than the taller smallcaps (for examples of petite caps, see the Emigre type families Mrs Eaves and Filosofia).
Equivalent OpenType tag: 'pcap'
Replaces figure glyphs set on uniform (tabular) widths with corresponding glyphs set on glyph-specific (proportional) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'pnum'
Replaces glyphs set on uniform widths (typically full or half-em) with proportionally spaced glyphs. The proportional variants are often used for the Latin characters in CJKV fonts, but may also be used for Kana in Japanese fonts.
Equivalent OpenType tag: 'pwid'
Replaces glyphs on other widths with glyphs set on widths of one quarter of an em (half an en). The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'qwid'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures, which the script determines as required to be used in normal conditions. This feature is important for some scripts to ensure correct glyph formation.
Equivalent OpenType tag: 'rlig'
Identifies glyphs in the font which have been designed for "ruby", from the old typesetting term for four-point-sized type. Japanese typesetting often uses smaller kana glyphs, generally in superscripted form, to clarify the meaning of kanji which may be unfamiliar to the reader.
Equivalent OpenType tag: 'ruby'
Replaces the default forms with the stylistic alternates. Many fonts contain alternate glyph designs for a purely esthetic effect; these don't always fit into a clear category like swash or historical. As in the case of swash glyphs, there may be more than one alternate form.
Equivalent OpenType tag: 'salt'
Replaces lining or oldstyle figures with inferior figures (smaller glyphs which sit lower than the standard baseline, primarily for chemical or mathematical notation). May also replace lowercase characters with alphabetic inferiors.
Equivalent OpenType tag: 'sinf'
Turns lowercase characters into small capitals. This corresponds to the common SC font layout. It is generally used for display lines set in Large & small caps, such as titles. Forms related to small capitals, such as oldstyle figures, may be included.
Equivalent OpenType tag: 'smcp'
Replaces 'traditional' Chinese or Japanese forms with the corresponding 'simplified' forms.
Equivalent OpenType tag: 'smpl'
In addition to, or instead of, stylistic alternatives of individual glyphs (see 'salt' feature), some fonts may contain sets of stylistic variant glyphs corresponding to portions of the character set, such as multiple variants for lowercase letters in a Latin font. Glyphs in stylistic sets may be designed to harmonise visually, interract in particular ways, or otherwise work together. Examples of fonts including stylistic sets are Zapfino Linotype and Adobe's Poetica. Individual features numbered sequentially with the tag name convention 'ss01' 'ss02' 'ss03' . 'ss20' provide a mechanism for glyphs in these sets to be associated via GSUB lookup indexes to default forms and to each other, and for users to select from available stylistic sets
Equivalent OpenType tag: 'ss01'
See the description for
Equivalent OpenType tag: 'ss02'
See the description for
Equivalent OpenType tag: 'ss03'
See the description for
Equivalent OpenType tag: 'ss04'
See the description for
Equivalent OpenType tag: 'ss05'
See the description for
Equivalent OpenType tag: 'ss06'
See the description for
Equivalent OpenType tag: 'ss07'
See the description for
Equivalent OpenType tag: 'ss08'
See the description for
Equivalent OpenType tag: 'ss09'
See the description for
Equivalent OpenType tag: 'ss10'
See the description for
Equivalent OpenType tag: 'ss11'
See the description for
Equivalent OpenType tag: 'ss12'
See the description for
Equivalent OpenType tag: 'ss13'
See the description for
Equivalent OpenType tag: 'ss14'
See the description for
Equivalent OpenType tag: 'ss15'
See the description for
Equivalent OpenType tag: 'ss16'
See the description for
Equivalent OpenType tag: 'ss17'
See the description for
Equivalent OpenType tag: 'ss18'
See the description for
Equivalent OpenType tag: 'ss19'
See the description for
Equivalent OpenType tag: 'ss20'
May replace a default glyph with a subscript glyph, or it may combine a glyph substitution with positioning adjustments for proper placement.
Equivalent OpenType tag: 'subs'
Replaces lining or oldstyle figures with superior figures (primarily for footnote indication), and replaces lowercase letters with superior letters (primarily for abbreviated French titles).
Equivalent OpenType tag: 'sups'
Replaces default character glyphs with corresponding swash glyphs. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'swsh'
Replaces the default glyphs with corresponding forms designed specifically for titling. These may be all-capital and/or larger on the body, and adjusted for viewing at larger sizes.
Equivalent OpenType tag: 'titl'
Replaces 'simplified' Japanese kanji forms with the corresponding 'traditional' forms. This is equivalent to the Traditional Forms feature, but explicitly limited to the traditional forms considered proper for use in personal names (as many as 205 glyphs in some fonts).
Equivalent OpenType tag: 'tnam'
Replaces figure glyphs set on proportional widths with corresponding glyphs set on uniform (tabular) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'tnum'
Replaces 'simplified' Chinese hanzi or Japanese kanji forms with the corresponding 'traditional' forms.
Equivalent OpenType tag: 'trad'
Replaces glyphs on other widths with glyphs set on widths of one third of an em. The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'twid'
Maps upper- and lowercase letters to a mixed set of lowercase and small capital forms, resulting in a single case alphabet (for an example of unicase, see the Emigre type family Filosofia). The letters substituted may vary from font to font, as appropriate to the design. If aligning to the x-height, smallcap glyphs may be substituted, or specially designed unicase forms might be used. Substitutions might also include specially designed figures. -
Equivalent OpenType tag: 'unic'
Allows the user to change from the default 0 to a slashed form. Some fonts contain both a default form of zero, and an alternative form which uses a diagonal slash through the counter. Especially in condensed designs, it can be difficult to distinguish between 0 and O (zero and capital O) in any situation where capitals and lining figures may be arbitrarily mixed.
Equivalent OpenType tag: 'zero'
The type of a font represented by a single font file. Font formats that consist of multiple files, for example Type 1 .PFM and .PFB, have separate enum values for each of the file types.
-Font type is not recognized by the DirectWrite font system.
OpenType font with CFF outlines.
OpenType font with TrueType outlines.
OpenType font that contains a TrueType collection.
Type 1 PFM font.
Type 1 PFB font.
Vector .FON font.
Bitmap .FON font.
Specifies algorithmic style simulations to be applied to the font face. Bold and oblique simulations can be combined via bitwise OR operation.
-Style simulations are not recommended for good typographic quality.
-Indicates that no simulations are applied to the font face.
Indicates that algorithmic emboldening is applied to the font face.
Indicates that algorithmic italicization is applied to the font face.
Represents the degree to which a font has been stretched compared to a font's normal aspect ratio. The enumerated values correspond to the usWidthClass definition in the OpenType specification. The usWidthClass represents an integer value between 1 and 9?lower values indicate narrower widths; higher values indicate wider widths.
-A font stretch describes the degree to which a font form is stretched from its normal aspect ratio, which is the original width to height ratio specified for the glyphs in the font. - The following illustration shows an example of Normal and Condensed stretches for the Rockwell Bold typeface.
Note??Values other than the ones defined in the enumeration are considered to be invalid, and are rejected by font API functions.
-Predefined font stretch : Not known (0).
Predefined font stretch : Ultra-condensed (1).
Predefined font stretch : Extra-condensed (2).
Predefined font stretch : Condensed (3).
Predefined font stretch : Semi-condensed (4).
Predefined font stretch : Normal (5).
Predefined font stretch : Medium (5).
Predefined font stretch : Semi-expanded (6).
Predefined font stretch : Expanded (7).
Predefined font stretch : Extra-expanded (8).
Predefined font stretch : Ultra-expanded (9).
Represents the style of a font face as normal, italic, or oblique.
-Three terms categorize the slant of a font: normal, italic, and oblique.
| Font style | Description |
|---|---|
| Normal | The characters in a normal, or roman, font are upright. - |
| Italic - | The characters in an italic font are truly slanted and appear as they were designed. - |
| Oblique | The characters in an oblique font are artificially slanted. |
?
For Oblique, the slant is achieved by performing a shear transformation on the characters from a normal font. When a true italic font is not available on a computer or printer, an oblique style can be generated from the normal font and used to simulate an italic font. The following illustration shows the normal, italic, and oblique font styles for the Palatino Linotype font. Notice how the italic font style has a more flowing and visually appealing appearance than the oblique font style, which is simply created by skewing the normal font style version of the text.
Note?? Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
-Font style : Normal.
Font style : Oblique.
Font style : Italic.
Represents the density of a typeface, in terms of the lightness or heaviness of the strokes. The enumerated values correspond to the usWeightClass definition in the OpenType specification. The usWeightClass represents an integer value between 1 and 999. Lower values indicate lighter weights; higher values indicate heavier weights.
-Weight differences are generally differentiated by an increased stroke or thickness that is associated with a given character in a typeface, as compared to a "normal" character from that same typeface. - The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
Note??Not all weights are available for all typefaces. When a weight is not available for a typeface, the closest matching weight is returned.
Font weight values less than 1 or greater than 999 are considered invalid, and they are rejected by font API functions.
-Predefined font weight : Thin (100).
Predefined font weight : Extra-light (200).
Predefined font weight : Ultra-light (200).
Predefined font weight : Light (300).
Predefined font weight : Normal (400).
Predefined font weight : Regular (400).
Predefined font weight : Medium (500).
Predefined font weight : Demi-bold (600).
Predefined font weight : Semi-bold (600).
Predefined font weight : Bold (700).
Predefined font weight : Extra-bold (800).
Predefined font weight : Ultra-bold (800).
Predefined font weight : Black (900).
Predefined font weight : Heavy (900).
Predefined font weight : Extra-black (950).
Predefined font weight : Ultra-black (950).
The informational string enumeration which identifies a string embedded in a font file.
-Indicates the string containing the unspecified name ID.
Indicates the string containing the copyright notice provided by the font.
Indicates the string containing a version number.
Indicates the string containing the trademark information provided by the font.
Indicates the string containing the name of the font manufacturer.
Indicates the string containing the name of the font designer.
Indicates the string containing the URL of the font designer (with protocol, e.g., http://, ftp://).
Indicates the string containing the description of the font. This may also contain revision information, usage recommendations, history, features, etc.
Indicates the string containing the URL of the font vendor (with protocol, e.g., http://, ftp://). If a unique serial number is embedded in the URL, it can be used to register the font.
Indicates the string containing the description of how the font may be legally used, or different example scenarios for licensed use.
Indicates the string containing the URL where additional licensing information can be found.
Indicates the string containing the GDI-compatible family name. Since GDI allows a maximum of four fonts per family, fonts in the same family may have different GDI-compatible family names (e.g., "Arial", "Arial Narrow", "Arial Black").
Indicates the string containing a GDI-compatible subfamily name.
Indicates the string containing the family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI. This name is typically only present if it differs from the GDI-compatible family name.
Indicates the string containing the subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
Contains sample text for display in font lists. This can be the font name or any other text that the designer thinks is the best example to display the font in.
The method used for line spacing in a text layout.
-The line spacing method is set by using the SetLineSpacing method of the
Line spacing depends solely on the content, adjusting to accommodate the size of fonts and inline objects.
Lines are explicitly set to uniform spacing, regardless of the size of fonts and inline objects. This can be useful to avoid the uneven appearance that can occur from font fallback.
Specifies how to apply number substitution on digits and related punctuation.
-Specifies that the substitution method should be determined based on the LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
If the culture is Arabic or Persian, specifies that the number shapes depend on the context. Either traditional or nominal number shapes are used, depending on the nearest preceding strong character or (if there is none) the reading direction of the paragraph.
Specifies that code points 0x30-0x39 are always rendered as nominal numeral shapes (ones of the European number), that is, no substitution is performed.
Specifies that numbers are rendered using the national number shapes as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
Specifies that numbers are rendered using the traditional shapes for the specified culture. For most cultures, this is the same as NativeNational. However, NativeNational results in Latin numbers for some Arabic cultures, whereasDWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL results in arabic numbers for all Arabic cultures.
Specifies the alignment of paragraph text along the flow direction axis, relative to the top and bottom of the flow's layout box.
-The top of the text flow is aligned to the top edge of the layout box.
The bottom of the text flow is aligned to the bottom edge of the layout box.
The center of the flow is aligned to the center of the layout box.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text. -
-The red, green, and blue color components of each pixel are assumed to occupy the same point.
Each pixel is composed of three vertical stripes, with red on the left, green in the center, and blue on the right. This is the most common pixel geometry for LCD monitors.
Each pixel is composed of three vertical stripes, with blue on the left, green in the center, and red on the right.
Specifies the direction in which reading progresses.
-Indicates that reading progresses from left to right.
Indicates that reading progresses from right to left.
Represents a method of rendering glyphs.
-Specifies that the rendering mode is determined automatically, based on the font and size.
Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground color of the text or retains the color of the background.
Specifies ClearType rendering with the same metrics as bi-level text. Glyphs can only be positioned on whole-pixel boundaries.
Specifies ClearType rendering with the same metrics as text rendering using GDI using a font created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than with bi-level text, but glyphs are still positioned on whole-pixel boundaries.
Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is typically used with small to medium font sizes (up to 16 ppem).
Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions. This is typically used at larger sizes to makes curves and diagonal lines look smoother, at the expense of some softness.
Specifies that rendering should bypass the rasterizer and use the outlines directly. This is typically used at very large sizes.
Indicates additional shaping requirements for text.
-Indicates that there is no additional shaping requirements for text. Text is shaped with the writing system default behavior.
Indicates that text should leave no visible control or format control characters.
Specifies the alignment of paragraph text along the reading direction axis, relative to the leading and trailing edge of the layout box.
-The leading edge of the paragraph text is aligned to the leading edge of the layout box.
The trailing edge of the paragraph text is aligned to the trailing edge of the layout box.
The center of the paragraph text is aligned to the center of the layout box.
Identifies a type of alpha texture.
-An alpha texture is a bitmap of alpha values, each representing opacity of a pixel or subpixel.
-Specifies an alpha texture for aliased text rendering (that is, each pixel is either fully opaque or fully transparent), with one byte per pixel.
Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and one byte per pixel in the vertical dimension.
Specifies the text granularity used to trim text overflowing the layout box.
-No trimming occurs. Text flows beyond the layout width.
Trimming occurs at a character cluster boundary.
Trimming occurs at a word boundary.
Specifies the word wrapping to be used in a particular multiline paragraph.
-Indicates that words are broken across lines to avoid text overflowing the layout box.
Indicates that words are kept within the same line even when it overflows the layout box. This option is often used with scrolling to reveal overflow text.
Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
-A value that specifies whether the factory object will be shared or isolated.
A
An address of a reference to the newly created DirectWrite factory object.
If this function succeeds, it returns
This function creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects. DirectWrite factory contains internal state data such as font loader registration and cached font data. In most cases it is recommended you use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state data, and thereby reduce memory usage. However, there are cases when it is desirable to reduce the impact of a component, such as a plug-in from an untrusted source, on the rest of the process, by sandboxing and isolating it from the rest of the process components. In such cases, it is recommended you use an isolated factory for the sandboxed component.
The following example shows how to create a shared DirectWrite factory.
if (SUCCEEDED(hr))
- { hr = Represents a physical font in a font collection. This interface is used to create font faces from physical fonts, or to retrieve information such as font face metrics or face names from existing font faces.
-Gets the font family to which the specified font belongs.
-When this method returns, contains an address of a reference to the font family object to which the specified font belongs.
If this method succeeds, it returns
Gets the weight, or stroke thickness, of the specified font.
-A value that indicates the weight for the specified font.
Gets the stretch, or width, of the specified font.
-A value that indicates the type of stretch, or width, applied to the specified font.
Gets the style, or slope, of the specified font.
-A value that indicates the type of style, or slope, of the specified font.
Determines whether the font is a symbol font.
-TRUE if the font is a symbol font; otherwise,
Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-When this method returns, contains an address to a reference to the newly created localized strings object.
If this method succeeds, it returns
Gets a localized strings collection containing the specified informational strings, indexed by locale name.
-A value that identifies the informational string to get. For example,
When this method returns, contains an address of a reference to the newly created localized strings object.
When this method returns, TRUE if the font contains the specified string ID; otherwise,
If the font does not contain the string specified by informationalStringID, the return value is
Gets a value that indicates what simulations are applied to the specified font.
-A value that indicates one or more of the types of simulations (none, bold, or oblique) applied to the specified font.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, contains a structure that has font metrics for the current font face. The metrics returned by this function are in font design units.
Determines whether the font supports a specified character.
-A Unicode (UCS-4) character value for the method to inspect.
When this method returns, TRUE if the font supports the specified character; otherwise,
Creates a font face object for the font.
-When this method returns, contains an address of a reference to the newly created font face object.
If this method succeeds, it returns
Gets the font family to which the specified font belongs.
-Gets the weight, or stroke thickness, of the specified font.
-Gets the stretch, or width, of the specified font.
-Gets the style, or slope, of the specified font.
-Determines whether the font is a symbol font.
-Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-Gets a value that indicates what simulations are applied to the specified font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Represents a family of related fonts.
-A font family is a set of fonts that share the same family name, such as "Times New Roman", but that differ in features. These feature differences include style, such as italic, and weight, such as bold. The following illustration shows examples of fonts that are members of the "Times New Roman" font family.
An
null ; // Get the font family.
- if (SUCCEEDED(hr))
- { hr = pFontCollection->GetFontFamily(i, &pFontFamily);
- }
- The font family name is used to specify the font family for text layout and text format objects. You can get a list of localized font family names from an
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- }
- Represents a list of fonts.
-Gets the font collection that contains the fonts in the font list.
-When this method returns, contains the address of a reference to the current
If this method succeeds, it returns
Gets the number of fonts in the font list.
-The number of fonts in the font list.
Gets a font given its zero-based index.
-Zero-based index of the font in the font list.
When this method returns, contains the address of a reference to the newly created
Gets the font collection that contains the fonts in the font list.
-Gets the number of fonts in the font list.
-Creates a localized strings object that contains the family names for the font family, indexed by locale name.
-The address of a reference to the newly created
If this method succeeds, it returns
The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the font that best matches the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
When this method returns, contains the address of a reference to the newly created
Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
An address of a reference to the newly created
Creates a localized strings object that contains the family names for the font family, indexed by locale name.
- The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- A built-in implementation of the
Obtains the length of the absolute file path from the font file reference key.
-Font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
Size of font file reference key in bytes.
Length of the file path string, not including the terminated
Obtains the absolute font file path from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The character array that receives the local file path.
The length of the file path character array.
If this method succeeds, it returns
Obtains the last write time of the file from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The time of the last font file modification.
Contains information about a glyph cluster.
-The total advance width of all glyphs in the cluster.
The number of text positions in the cluster.
Indicates whether a line can be broken right after the cluster.
Indicates whether the cluster corresponds to a whitespace character.
Indicates whether the cluster corresponds to a newline character.
Indicates whether the cluster corresponds to a soft hyphen character.
Indicates whether the cluster is read from right to left.
Reserved for future use.
The
The number of font design units per em unit. Font files use their own coordinate system of font design units. A font design unit is the smallest measurable unit in the em square, an imaginary square that is used to size and align glyphs. The concept of em square is used as a reference scale factor when defining font size and device transformation semantics. The size of one em square is also commonly used to compute the paragraph identation value.
The ascent value of the font face in font design units. Ascent is the distance from the top of font character alignment box to the English baseline.
The descent value of the font face in font design units. Descent is the distance from the bottom of font character alignment box to the English baseline.
The line gap in font design units. Recommended additional white space to add between lines to improve legibility. The recommended line spacing (baseline-to-baseline distance) is the sum of ascent, descent, and lineGap. The line gap is usually positive or zero but can be negative, in which case the recommended line spacing is less than the height of the character alignment box.
The cap height value of the font face in font design units. Cap height is the distance from the English baseline to the top of a typical English capital. Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
The x-height value of the font face in font design units. x-height is the distance from the English baseline to the top of lowercase letter "x", or a similar lowercase character.
The underline position value of the font face in font design units. Underline position is the position of underline relative to the English baseline. The value is usually made negative in order to place the underline below the baseline.
The suggested underline thickness value of the font face in font design units.
The strikethrough position value of the font face in font design units. Strikethrough position is the position of strikethrough relative to the English baseline. The value is usually made positive in order to place the strikethrough above the baseline.
The suggested strikethrough thickness value of the font face in font design units.
Specifies the metrics of an individual glyph. The units depend on how the metrics are obtained.
-Specifies the X offset from the glyph origin to the left edge of the black box. The glyph origin is the current horizontal writing position. A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally. The value is negative when the right edge of the black box overhangs the layout box.
Specifies the vertical offset from the vertical origin to the top of the black box. Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically. Note that the term "origin" by itself denotes the horizontal origin. The vertical origin is different. Its Y coordinate is specified by verticalOriginY value, and its X coordinate is half the advanceWidth to the right of the horizontal origin.
Specifies the vertical distance from the bottom edge of the black box to the advance height. This is positive when the bottom edge of the black box is within the layout box, or negative when the bottom edge of black box overhangs the layout box.
Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system. The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing and the top (that is, yMax) of the glyph's bounding box.
The optional adjustment to a glyph's position.
-An glyph offset changes the position of a glyph without affecting the pen position. Offsets are in logical, pre-transform units.
-The offset in the advance direction of the run. A positive advance offset moves the glyph to the right (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
The offset in the ascent direction, that is, the direction ascenders point. A positive ascender offset moves the glyph up (in pre-transform coordinates). A negative ascender offset moves the glyph down.
Describes the region obtained by a hit test.
-The first text position within the hit region.
The number of text positions within the hit region.
The x-coordinate of the upper-left corner of the hit region.
The y-coordinate of the upper-left corner of the hit region.
The width of the hit region.
The height of the hit region.
The BIDI level of the text positions within the hit region.
true if the hit region contains text; otherwise, false.
Contains properties describing the geometric measurement of an - application-defined inline object.
-The width of the inline object.
The height of the inline object.
The distance from the top of the object to the point where it is lined up with the adjacent text. If the baseline is at the bottom, then baseline simply equals height.
A Boolean flag that indicates whether the object is to be placed upright or alongside the text baseline for vertical text.
Contains information about a formatted line of text.
-The number of text positions in the text line. This includes any trailing whitespace and newline characters.
The number of whitespace positions at the end of the text line. Newline sequences are considered whitespace.
The number of characters in the newline sequence at the end of the text line. If the count is zero, then the text line was either wrapped or it is the end of the text.
The height of the text line.
The distance from the top of the text line to its baseline.
The line is trimmed.
Indicates how much any visible DIPs (device independent pixels) overshoot each side of the layout or inline objects.
Positive overhangs indicate that the visible area extends outside the layout box or inline object, while negative values mean there is whitespace inside. The returned values are unaffected by rendering transforms or pixel snapping. Additionally, they may not exactly match the final target's pixel bounds after applying grid fitting and hinting.
-The distance from the left-most visible DIP to its left-alignment edge.
The distance from the top-most visible DIP to its top alignment edge.
The distance from the right-most visible DIP to its right-alignment edge.
The distance from the bottom-most visible DIP to its lower-alignment edge.
Stores the association of text and its writing system script, as well as some display attributes.
-The zero-based index representation of writing system script.
A value that indicates additional shaping requirement of text.
Shaping output properties for an output glyph.
-Indicates that the glyph is shaped alone.
Reserved for future use.
Contains information regarding the size and placement of strikethroughs. All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the strikethrough, measured parallel to the baseline.
A value that indicates the thickness of the strikethrough, measured perpendicular to the baseline.
A value that indicates the offset of the strikethrough from the baseline. A positive offset represents a position below the baseline and a negative offset is above. Typically, the offset will be negative.
Reading direction of the text associated with the strikethrough. This value is used to interpret whether the width value runs horizontally or vertically.
Flow direction of the text associated with the strikethrough. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters containing the locale of the text that is the strikethrough is being drawn over.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Contains the metrics associated with text after layout. All coordinates are in device independent pixels (DIPs).
-A value that indicates the left-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the top-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the width of the formatted text, while ignoring trailing whitespace at the end of each line.
The width of the formatted text, taking into account the trailing whitespace at the end of each line.
The height of the formatted text. The height of an empty string is set to the same value as that of the default font.
The initial width given to the layout. It can be either larger or smaller than the text content width, depending on whether the text was wrapped.
Initial height given to the layout. Depending on the length of the text, it may be larger or smaller than the text content height.
The maximum reordering count of any line of text, used to calculate the most number of hit-testing boxes needed. If the layout has no bidirectional text, or no text at all, the minimum level is 1.
Specifies the trimming option for text overflowing the layout box.
-A value that specifies the text granularity used to trim text overflowing the layout box.
A character code used as the delimiter that signals the beginning of the portion of text to be preserved. Most useful for path ellipsis, where the delimiter would be a slash.
A value that indicates how many occurrences of the delimiter to step back.
Contains a set of typographic features to be applied during text shaping.
-A reference to a structure that specifies properties used to identify and execute typographic features in the font.
A value that indicates the number of features being applied to a font face.
Contains information about the width, thickness, offset, run height, reading direction, and flow direction of an underline.
-All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the underline, measured parallel to the baseline.
A value that indicates the thickness of the underline, measured perpendicular to the baseline.
A value that indicates the offset of the underline from the baseline. A positive offset represents a position below the baseline (away from the text) and a negative offset is above (toward the text).
A value that indicates the height of the tallest run where the underline is applied.
A value that indicates the reading direction of the text associated with the underline. This value is used to interpret whether the width value runs horizontally or vertically.
A value that indicates the flow direction of the text associated with the underline. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters which contains the locale of the text that the underline is being drawn under. For example, in vertical text, the underline belongs on the left for Chinese but on the right for Japanese.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Specifies how the alpha value of a bitmap or render target should be treated.
-The
When describing an RGBA color using straight alpha, the alpha value of the color is stored in the alpha channel. For example, to describe a red color that is 60% opaque, you'd use the following values: (255, 0, 0, 255 * 0.6) = (255, 0, 0, 153). The 255 value indicates full red, and 153 (which is 60 percent of 255) indicates that the color should have an opacity of 60 percent.
When describing an RGBA color using premultiplied alpha, each color is multiplied by the alpha value: (255 * 0.6, 0 * 0.6, 0 * 0.6, 255 * 0.6) = (153, 0, 0, 153).
Regardless of the alpha mode of the render target, D2D1_COLOR_F values are always interpreted as straight alpha. For example, when specifying the color of an
Regardless of the alpha mode setting, a render target's contents support transparency. For example, if you draw a partially transparent red rectangle with a render target with an alpha mode of
If you draw a partially transparent red rectangle when the alpha mode is
If you specify an alpha mode other than
You can use the SetTextAntialiasMode method to change the text antialias mode back to
The alpha value might not be meaningful.
The alpha value has been premultiplied. Each color is first scaled by the alpha value. The alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. If a color channel value in a premultiplied format is greater than the alpha channel, the standard source-over blending math results in an additive blend.
The alpha value has not been premultiplied. The alpha channel indicates the transparency of the color.
The alpha value is ignored.
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Specifies whether an arc should be greater than 180 degrees.
-An arc's sweep should be 180 degrees or less.
An arc's sweep should be 180 degrees or greater.
Specifies the algorithm that is used when images are scaled or rotated.
- To stretch an image, each pixel in the original image must be mapped to a group of pixels in the larger image. To shrink an image, groups of pixels in the original image must be mapped to single pixels in the smaller image. The effectiveness of the algorithms that perform these mappings determines the quality of a scaled image. Algorithms that produce higher-quality scaled images tend to require more processing time.
Use the exact color of the nearest bitmap pixel to the current rendering pixel.
Interpolate a color from the four bitmap pixels that are the nearest to the rendering pixel.
Describes the shape at the end of a line or segment.
-The following illustration shows the available cap styles for lines or segments. The red portion of the line shows the extra area added by the line cap setting.
-A cap that does not extend past the last point of the line. Comparable to cap used for objects other than lines.
Half of a square that has a length equal to the line thickness.
A semicircle that has a diameter equal to the line thickness.
An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line.
Specifies the different methods by which two geometries can be combined.
-The following illustration shows the different geometry combine modes. -
-The two regions are combined by taking the union of both. Given two geometries, A and B, the resulting geometry is geometry A + geometry B.
The two regions are combined by taking their intersection. The new area consists of the overlapping region between the two geometries.
The two regions are combined by taking the area that exists in the first region but not the second and the area that exists in the second region but not the first. Given two geometries, A and B, the new region consists of (A-B) + (B-A).
The second region is excluded from the first. Given two geometries, A and B, the area of geometry B is removed from the area of geometry A, producing a region that is A-B.
Specifies additional features supportable by a compatible render target when it is created. This enumeration allows a bitwise combination of its member values.
-Use this enumeration when creating a compatible render target with the CreateCompatibleRenderTarget method. For more information about compatible render targets, see the Render Targets Overview.
The
The render target supports no additional features.
The render target supports interoperability with the Windows Graphics Device Interface (GDI).
Describes the sequence of dashes and gaps in a stroke.
-The following illustration shows several available dash styles. For more information, see the Stroke Style Example.
-A solid line with no breaks.
A dash followed by a gap of equal length. The dash and the gap are each twice as long as the stroke thickness.
The equivalent dash array for
A dot followed by a longer gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap, followed by another dot, followed by another gap.
The equivalent dash array for
The dash pattern is specified by an array of floating-point values.
Indicates the type of information provided by the Direct2D Debug Layer.
-To receive debugging messages, you must install the Direct2D Debug Layer.
-Specifies how a device context is initialized for GDI rendering when it is retrieved from the render target.
-Use this enumeration with the
The current contents of the render target are copied to the device context when it is initialized.
The device context is cleared to transparent black when it is initialized.
Specifies whether text snapping is suppressed or clipping to the layout rectangle is enabled. This enumeration allows a bitwise combination of its member values.
-Text is not vertically snapped to pixel boundaries. This setting is recommended for text that is being animated.
Text is clipped to the layout rectangle.
Text is vertically snapped to pixel boundaries and is not clipped to the layout rectangle.
Specifies how a brush paints areas outside of its normal content area.
-For an
For an example, see the Draw Extend Mode Example.
-Repeat the edge pixels of the brush's content for all regions outside the normal content area.
Repeat the brush's content.
The same as
Specifies whether Direct2D provides synchronization for an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread, and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU; however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Describes the minimum DirectX support required for hardware rendering by a render target.
-Direct2D determines whether the video card provides adequate hardware rendering support.
The video card must support DirectX 9.
The video card must support DirectX 10.
Indicates whether a specific
Indicates whether a specific
Specifies how the intersecting areas of geometries or figures are combined to form the area of the composite geometry.
-Use the
Direct2D fills the interior of a path by using one of the two fill modes specified by this enumeration:
To see the difference between the winding and alternate fill modes, assume that you have four circles with the same center and a different radius, as shown in the following illustration. The first one has the radius of 25, the second 50, the third 75, and the fourth 100.
The following illustration shows the shape filled by using the alternate fill mode. Notice that the center and third ring are not filled. This is because a ray drawn from any point in either of those two rings passes through an even number of segments.
The following illustration explains this process.
The following illustration shows how the same shape is filled when the winding fill mode is specified.
Notice that all the rings are filled. This is because all the segments run in the same direction, so a ray drawn from any point will cross one or more segments, and the sum of the crossings will not equal zero.
The following illustration explains this process. The red arrows represent the direction in which the segments are drawn and the black arrow represents an arbitrary ray that runs from a point in the innermost ring. Starting with a value of zero, for each segment that the ray crosses, a value of one is added for every clockwise intersection. All points lie in the fill region in this illustration, because the count does not equal zero.
-Determines whether a point is in the fill region by drawing a ray from that point to infinity in any direction, and then counting the number of path segments within the given shape that the ray crosses. If this number is odd, the point is in the fill region; if even, the point is outside the fill region.
Determines whether a point is in the fill region of the path by drawing a ray from that point to infinity in any direction, and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left, as long as left and right are seen from the perspective of the ray. After counting the crossings, if the result is zero, then the point is outside the path. Otherwise, it is inside the path.
Specifies which gamma is used for interpolation.
-Interpolating in a linear gamma space (
The first gradient is interpolated linearly in the space of the render target (sRGB in this case), and one can see the dark bands between each color. The second gradient uses a gamma-correct linear interpolation, and thus does not exhibit the same variations in brightness.
-Interpolation is performed in the standard RGB (sRGB) gamma.
Interpolation is performed in the linear-gamma color space.
Describes how one geometry object is spatially related to another geometry object.
-The relationship between the two geometries cannot be determined. This value is never returned by any D2D method.
The two geometries do not intersect at all.
The instance geometry is entirely contained by the passed-in geometry.
The instance geometry entirely contains the passed-in geometry.
The two geometries overlap but neither completely contains the other.
Specifies how a geometry is simplified to an
Specifies options that can be applied when a layer resource is applied to create a layer.
-ClearType antialiasing must use the current contents of the render target to blend properly. When a pushed layer requests initializing for ClearType, Direct 2D copies the current contents of the render target into the layer so that ClearType antialiasing can be performed. Rendering ClearType text into a transparent layer does not produce the desired results.
A small performance hit from re-copying content occurs when
The text in this layer does not use ClearType antialiasing.
The layer renders correctly for ClearType text. If the render target is set to ClearType, the layer continues to render ClearType. If the render target is set to ClearType and this option is not specified, the render target will be set to render gray-scale until the layer is popped. The caller can override this default by calling SetTextAntialiasMode while within the layer. This flag is slightly slower than the default.
Describes the shape that joins two lines or segments.
- A miter limit affects how sharp miter joins are allowed to be. If the line join style is
The following illustration shows different line join settings for the same stroked path geometry. For more information, see Stroke Style Example.
-Regular angular vertices.
Beveled vertices.
Rounded vertices.
Regular angular vertices unless the join would extend beyond the miter limit; otherwise, beveled vertices.
Indicates the measuring method used for text layout.
-Specifies that text is measured using glyph ideal metrics whose values are independent to the current display resolution.
Specifies that text is measured using glyph display-compatible metrics whose values tuned for the current display resolution.
Specifies that text is measured using the same glyph display metrics as text measured by GDI using a font created with CLEARTYPE_NATURAL_QUALITY.
Describes whether an opacity mask contains graphics or text. Direct2D uses this information to determine which gamma space to use when blending the opacity mask.
-The opacity mask contains graphics. The opacity mask is blended in the gamma 2.2 color space.
The opacity mask contains non-GDI text. The gamma space used for blending is obtained from the render target's text rendering parameters. (
The opacity mask contains text rendered using the GDI-compatible rendering mode. The opacity mask is blended using the gamma for GDI rendering.
Indicates whether a segment should be stroked and whether the join between this segment and the previous one should be smooth. This enumeration allows a bitwise combination of its member values.
-The segment is joined as specified by the
The segment is not stroked.
The segment is always joined with the one preceding it using a round line join, regardless of which
Describes how a render target behaves when it presents its content. This enumeration allows a bitwise combination of its member values.
-The render target waits until the display refreshes to present and discards the frame upon presenting.
The render target does not discard the frame upon presenting.
The render target does not wait until the display refreshes to present.
Describes whether a render target uses hardware or software rendering, or if Direct2D should select the rendering mode.
-Not every render target supports hardware rendering. For more information, see the Render Targets Overview.
-The render target uses hardware rendering, if available; otherwise, it uses software rendering.
The render target uses software rendering only.
The render target uses hardware rendering only.
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
Defines the direction that an elliptical arc is drawn.
-Arcs are drawn in a counterclockwise (negative-angle) direction.
Arcs are drawn in a clockwise (positive-angle) direction.
Describes the antialiasing mode used for drawing text.
-This enumeration is used with the SetTextAntialiasMode of an
By default, Direct2D renders text in ClearType mode. Factors that can downgrade the default quality to grayscale or aliased:
Use the system default. See Remarks.
Use ClearType antialiasing.
Use grayscale antialiasing.
Do not use antialiasing.
Describes whether a window is occluded.
-If the window was occluded the last time EndDraw was called, the next time the render target calls CheckWindowState, it returns
The window is not occluded.
The window is occluded.
Indicates whether the specified matrix is invertible.
-The matrix to test.
true if the matrix was inverted; otherwise, false.
Tries to invert the specified matrix.
-The matrix to invert.
true if the matrix was inverted; otherwise, false.
Creates a skew transformation that has the specified x-axis angle, y-axis angle, and center point.
-The x-axis skew angle, which is measured in degrees counterclockwise from the y-axis.
The y-axis skew angle, which is measured in degrees counterclockwise from the x-axis.
The center point of the skew operation.
When this method returns, contains the rotation transformation. You must allocate storate for this parameter.
Creates a factory object that can be used to create Direct2D resources.
-The threading model of the factory and the resources it creates.
A reference to the IID of
The level of detail provided to the debugging layer.
When this method returns, contains the address to a reference to the new factory.
If this function succeeds, it returns
The
Creates a rotation transformation that rotates by the specified angle about the specified point.
-The clockwise rotation angle, in degrees.
The point about which to rotate.
When this method returns, contains the new rotation transformation. You must allocate storage for this parameter.
Rotation occurs in the plane of the 2-D surface.
-Issues drawing commands to a GDI device context.
-To create an
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
To enable the DC render target to work with GDI, set its pixel format to
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
When you use an
It's possible for GDI to apply a GDI transform (through the SetWorldTransform method) or other effect to the same DC used by the render target, in which case GDI transforms the bitmap produced by Direct2D. Using a GDI transform to transform the Direct2D content has the potential to degrade the visual quality of the output, because you're transforming a bitmap for which antialiasing and subpixel positioning have already been calculated.
For example, suppose you use the render target to draw a scene that contains antialiased geometries and text. If you use a GDI transform to apply a scale transform to the DC and scale the scene so that it's 10 times larger, you'll see pixelization and jagged edges. (If, however, you applied a similar transform using Direct2D, the visual quality of the scene would not be degraded.)
In some cases, it might not be obvious that GDI is performing additional processing that might degrade the quality of the Direct2D content. For example, on a right-to-left (RTL) build of Windows, content rendered by an
Depending on the type of content being rendered, you might want to prevent the inversion. If the Direct2D content includes ClearType text, this inversion will degrade the quality of the text.
You can control RTL rendering behavior by using the SetLayout GDI function. To prevent the mirroring, call the SetLayout GDI function and specify LAYOUT_BITMAPORIENTATIONPRESERVED as the only value for the second parameter (do not combine it with LAYOUT_RTL), as shown in the following example:
SetLayout(m_hwnd, LAYOUT_BITMAPORIENTATIONPRESERVED);Binds the render target to the device context to which it issues drawing commands.
-The device context to which the render target issues drawing commands.
The dimensions of the handle to a device context (
If this method succeeds, it returns
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
-Represents the drawing state of a render target: the antialiasing mode, transform, tags, and text-rendering options.
-To create an
A drawing state block is a device-independent resource; you can create it once and retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the antialiasing mode, transform, and tags portion of the drawing state.
-When this method returns, contains the antialiasing mode, transform, and tags portion of the drawing state. You must allocate storage for this parameter.
Specifies the antialiasing mode, transform, and tags portion of the drawing state.
-The antialiasing mode, transform, and tags portion of the drawing state.
Specifies the text-rendering configuration of the drawing state.
-The text-rendering configuration of the drawing state, or
Retrieves the text-rendering configuration of the drawing state.
-When this method returns, contains the address of a reference to an
Retrieves or sets the antialiasing mode, transform, and tags portion of the drawing state.
-Retrieves or sets the text-rendering configuration of the drawing state.
-Represents an ellipse.
-To create an elipse geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Represents a geometry resource and defines a set of helper methods for manipulating and measuring geometric shapes. Interfaces that inherit from
There are several types of Direct2D geometry objects: a simple geometry (
Direct2D geometries enable you to describe two-dimensional figures and also offer many uses, such as defining hit-test regions, clip regions, and even animation paths.
Direct2D geometries are immutable and device-independent resources created by
Gets the bounds of the geometry after it has been widened by the specified stroke width and style and transformed by the specified matrix.
-The amount by which to widen the geometry by stroking its outline.
The style of the stroke that widens the geometry.
A transform to apply to the geometry after the geometry is transformed and after the geometry has been stroked.
When this method returns, contains the bounds of the widened geometry. You must allocate storage for this parameter.
Determines whether the geometry's stroke contains the specified point given the specified stroke thickness, style, and transform.
-The point to test for containment.
The thickness of the stroke to apply.
The style of stroke to apply.
The transform to apply to the stroked geometry.
When this method returns, contains a boolean value set to true if the geometry's stroke contains the specified point; otherwise, false. You must allocate storage for this parameter.
Indicates whether the area filled by the geometry would contain the specified point given the specified flattening tolerance.
-The point to test.
The transform to apply to the geometry prior to testing for containment, or
The numeric accuracy with which the precise geometric path and path intersection is calculated. Points missing the fill by less than the tolerance are still considered inside. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a
Describes the intersection between this geometry and the specified geometry. The comparison is performed by using the specified flattening tolerance.
-The geometry to test.
The transform to apply to inputGeometry, or
The maximum bounds on the distance between points in the polygonal approximation of the geometries. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to a value that describes how this geometry is related to inputGeometry. You must allocate storage for this parameter.
When interpreting the returned relation value, it is important to remember that the member
For more information about how to interpret other possible return values, see
Computes the outline of the geometry and writes the result to an
If this method succeeds, it returns
The Outline method allows the caller to produce a geometry with an equivalent fill to the input geometry, with the following additional properties:
Additionally, the Outline method can be useful in removing redundant portions of said geometries to simplify complex geometries. It can also be useful in combination with
Computes the area of the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The transform to apply to this geometry before computing its area, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this this method returns, contains a reference to the area of the transformed, flattened version of this geometry. You must allocate storage for this parameter.
Calculates the point and tangent vector at the specified distance along the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The distance along the geometry of the point and tangent to find. If this distance is less then 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry.
The transform to apply to the geometry before calculating the specified point and tangent, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to the tangent vector at the specified distance along the geometry. If the geometry is empty, this vector contains NaN as its x and y values. You must allocate storage for this parameter.
The location at the specified distance along the geometry. If the geometry is empty, this point contains NaN as its x and y values.
Widens the geometry by the specified stroke and writes the result to an
If this method succeeds, it returns
Gets the
Gets the
Creates Direct2D resources.
-The
A factory defines a set of CreateResource methods that can produce the following drawing resources:
To create an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so, this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note that the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU, however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Forces the factory to refresh any system defaults that it might have changed since factory creation.
-If this method succeeds, it returns
You should call this method before calling the GetDesktopDpi method, to ensure that the system DPI is current.
-Retrieves the current desktop dots per inch (DPI). To refresh this value, call ReloadSystemMetrics.
-Use this method to obtain the system DPI when setting physical pixel values, such as when you specify the size of a window.
- Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Transforms the specified geometry and stores the result as an
If this method succeeds, it returns
Like other resources, a transformed geometry the inherits the resource space and threading policy of the factory that created it. This object is immutable.
When stroking a transformed geometry with the DrawGeometry method, the stroke width is not affected by the transform applied to the geometry. The stroke width is only affected by the world transform.
-Creates an empty
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a render target that renders to a Microsoft Windows Imaging Component (WIC) bitmap.
-The bitmap that receives the rendering output of the render target.
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
Your application should create render targets once and hold onto them for the life of the application or until the
Creates an
If this method succeeds, it returns
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the
Creates a render target that draws to a DirectX Graphics Infrastructure (DXGI) surface.
-The
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
To write to a Direct3D surface, you obtain an
A DXGI surface render target is a type of
The DXGI surface render target and the DXGI surface must use the same DXGI format. If you specify the DXGI_FORMAT_UNKOWN format when you create the render target, it will automatically use the surface's format.
The DXGI surface render target does not perform DXGI surface synchronization.
For more information about creating and using DXGI surface render targets, see the Direct2D and Direct3D Interoperability Overview.
To work with Direct2D, the Direct3D device that provides the
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Creates a render target that draws to a Windows Graphics Device Interface (GDI) device context.
-The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. To enable the device context (DC) render target to work with GDI, set the DXGI format to
When this method returns, dcRenderTarget contains the address of the reference to the
If this method succeeds, it returns
Before you can render with a DC render target, you must use the render target's BindDC method to associate it with a GDI DC. Do this for each different DC and whenever there is a change in the size of the area you want to draw to.
To enable the DC render target to work with GDI, set the render target's DXGI format to
Your application should create render targets once and hold on to them for the life of the application or until the render target's EndDraw method returns the
Represents a composite geometry, composed of other
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one.
CreatingTo create a
Direct2D geometries are immutable and device-independent resources created by
Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-A value that indicates how the intersecting areas of the geometries contained in this geometry group are combined.
Indicates the number of geometry objects in the geometry group.
-The number of geometries in the
Retrieves the geometries in the geometry group.
-When this method returns, contains the address of a reference to an array of geometries to be filled by this method. The length of the array is specified by the geometryCount parameter. If the array is
A value indicating the number of geometries to return in the geometries array. If this value is less than the number of geometries in the geometry group, the remaining geometries are omitted. If this value is larger than the number of geometries in the geometry group, the extra geometries are set to
The returned geometries are referenced and counted, and the caller must release them.
-Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-Indicates the number of geometry objects in the geometry group.
-Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Specifies the method used to determine which points are inside the geometry described by this geometry sink and which points are outside.
-The method used to determine whether a given point is part of the geometry.
The fill mode defaults to
Specifies stroke and join options to be applied to new segments added to the geometry sink.
-Stroke and join options to be applied to new segments added to the geometry sink.
After this method is called, the specified segment flags are applied to each segment subsequently added to the sink. The segment flags are applied to every additional segment until this method is called again and a different set of segment flags is specified.
-Starts a new figure at the specified point.
-The point at which to begin the new figure.
Whether the new figure should be hollow or filled.
If this method is called while a figure is currently in progress, the interface is invalidated and all future methods will fail.
-Creates a sequence of lines using the specified points and adds them to the geometry sink.
-A reference to an array of one or more points that describe the lines to draw. A line is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the first point in the array. if the array contains additional points, a line is drawn from the first point to the second point in the array, from the second point to the third point, and so on.
The number of points in the points array.
Creates a sequence of cubic Bezier curves and adds them to the geometry sink.
-A reference to an array of Bezier segments that describes the Bezier curves to create. A curve is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the end point of the first Bezier segment in the array. if the array contains additional Bezier segments, each subsequent Bezier segment uses the end point of the preceding Bezier segment as its start point.
The number of Bezier segments in the beziers array.
Ends the current figure; optionally, closes it.
-A value that indicates whether the current figure is closed. If the figure is closed, a line is drawn between the current point and the start point specified by BeginFigure.
Calling this method without a matching call to BeginFigure places the geometry sink in an error state; subsequent calls are ignored, and the overall failure will be returned when the Close method is called.
-Closes the geometry sink, indicates whether it is in an error state, and resets the sink's error state.
-If this method succeeds, it returns
Do not close the geometry sink while a figure is still in progress; doing so puts the geometry sink in an error state. For the close operation to be successful, there must be one EndFigure call for each call to BeginFigure.
After calling this method, the geometry sink might not be usable. Direct2D implementations of this interface do not allow the geometry sink to be modified after it is closed, but other implementations might not impose this restriction.
-Creates a line segment between the current point and the specified end point and adds it to the geometry sink.
-The end point of the line to draw.
Creates a cubic Bezier curve between the current point and the specified end point.
-A structure that describes the control points and end point of the Bezier curve to add.
Creates a quadratic Bezier curve between the current point and the specified endpoint.
-A structure that describes the control point and the endpoint of the quadratic Bezier curve to add.
Adds a sequence of quadratic Bezier segments as an array in a single call.
-An array of a sequence of quadratic Bezier segments.
A value indicating the number of quadratic Bezier segments in beziers.
Adds a single arc to the path geometry.
-The arc segment to add to the figure.
Represents an collection of
To create an
A gradient stop collection is a device-dependent resource: your application should create gradient stop collections after it initializes the render target with which the gradient stop collection will be used, and recreate the gradient stop collection whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Retrieves the number of gradient stops in the collection.
-The number of gradient stops in the collection.
Copies the gradient stops from the collection into an array of
Gradient stops are copied in order of position, starting with the gradient stop with the smallest position value and progressing to the gradient stop with the largest position value.
-Indicates the gamma space in which the gradient stops are interpolated.
-The gamma space in which the gradient stops are interpolated.
Indicates the behavior of the gradient outside the normalized gradient range.
-The behavior of the gradient outside the [0,1] normalized gradient range.
Retrieves the number of gradient stops in the collection.
-Indicates the gamma space in which the gradient stops are interpolated.
-Indicates the behavior of the gradient outside the normalized gradient range.
-Represents the backing store required to render a layer.
-To create a layer, call the CreateLayer method of the render target where the layer will be used. To draw to a layer, push the layer to the render target stack by calling the PushLayer method. After you have finished drawing to the layer, call the PopLayer method.
Between PushLayer and PopLayer calls, the layer is in use and cannot be used by another render target.
If the size of the layer is not specified, the corresponding PushLayer call determines the minimum layer size, based on the layer content bounds and the geometric mask. The layer resource can be larger than the size required by PushLayer without any rendering artifacts.
If the size of a layer is specified, or if the layer has been used and the required backing store size as calculated during PushLayer is larger than the layer, then the layer resource is expanded on each axis monotonically to ensure that it is large enough. The layer resource never shrinks in size.
CreatingTo create a layer, call the CreateLayer method of the render target where the layer will be used.
A layer is a device-dependent resource: your application should create layers after it initializes the render target with which the layers will be used, and recreate the layers whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Gets the size of the layer in device-independent pixels.
-The size of the layer in device-independent pixels.
Gets the size of the layer in device-independent pixels.
-Paints an area with a linear gradient.
-An
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush start point and end point are also transformed.
It is possible to specify a gradient axis that does not completely fill the area that is being painted. When this occurs, the
To create a linear gradient brush, use the
A linear gradient brush is a device-dependent resource: your application should create linear gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Sets the starting coordinates of the linear gradient in the brush's coordinate space.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Sets the ending coordinates of the linear gradient in the brush's coordinate space.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the starting coordinates of the linear gradient.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the ending coordinates of the linear gradient.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Retrieves or sets the starting coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves or sets the ending coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Represents a set of vertices that form a list of triangles.
-To create a mesh, call the
A mesh is a device-dependent resource: your application should create meshes after it initializes the render target with which the meshes will be used, and recreate the meshes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Opens the mesh for population.
-When this method returns, contains a reference to a reference to an
If this method succeeds, it returns
Represents a complex shape that may be composed of arcs, curves, and lines.
-An
To create a path geometry, use the
Retrieves the geometry sink that is used to populate the path geometry with figures and segments.
-When this method returns, geometrySink contains the address of a reference to the geometry sink that is used to populate the path geometry with figures and segments. This parameter is passed uninitialized.
Because path geometries are immutable and can only be populated once, it is an error to call Open on a path geometry more than once.
Note that the fill mode defaults to
Copies the contents of the path geometry to the specified
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-A reference that receives the number of segments in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of figures in the path geometry.
-A reference that receives the number of figures in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-Retrieves the number of figures in the path geometry.
-Paints an area with a radial gradient.
-The
The brush maps the gradient stop position 0.0f of the gradient origin, and the position 1.0f is mapped to the ellipse boundary. When the gradient origin is within the ellipse, the contents of the ellipse enclose the entire [0, 1] range of the brush gradient stops. If the gradient origin is outside the bounds of the ellipse, the brush still works, but its gradient is not well-defined.
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps just one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush ellipse and gradient origin are also transformed.
It is possible to specify an ellipse that does not completely fill area being painted. When this occurs, the
To create a radial gradient brush, use the
A radial gradient brush is a device-dependent resource: your application should create radial gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Specifies the center of the gradient ellipse in the brush's coordinate space.
-The center of the gradient ellipse, in the brush's coordinate space.
Specifies the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse.
Specifies the x-radius of the gradient ellipse, in the brush's coordinate space.
-The x-radius of the gradient ellipse. This value is in the brush's coordinate space.
Specifies the y-radius of the gradient ellipse, in the brush's coordinate space.
-The y-radius of the gradient ellipse. This value is in the brush's coordinate space.
Retrieves the center of the gradient ellipse.
-The center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the x-radius of the gradient ellipse.
-The x-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the y-radius of the gradient ellipse.
-The y-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the
Retrieves or sets the center of the gradient ellipse.
-Retrieves or sets the offset of the gradient origin relative to the gradient ellipse's center.
-Retrieves or sets the x-radius of the gradient ellipse.
-Retrieves or sets the y-radius of the gradient ellipse.
-Retrieves the
Describes a two-dimensional rectangle.
-To create a rectangle geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Contains a reference to a rectangle that describes the rectangle geometry's dimensions when this method returns. You must allocate storage for this parameter.
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-A reference that receives a rounded rectangle that describes this rounded rectangle geometry. You must allocate storage for this parameter.
Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Paints an area with a solid color.
-To create a solid color brush, use the
A solid color brush is a device-dependent resource. (For more information about resources, see Resources Overview.)
-Specifies the color of this solid-color brush.
-The color of this solid-color brush.
To help create colors, Direct2D provides the ColorF class. It offers several helper methods for creating colors and provides a set or predefined colors.
-Retrieves the color of the solid color brush.
-The color of this solid color brush.
Retrieves or sets the color of the solid color brush.
-Describes the caps, miter limit, line join, and dash information for a stroke.
-To create a stroke style, use the
A stroke style is a device-indenpendent resource; you can create it once then retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the type of shape used at the beginning of a stroke.
-The type of shape used at the beginning of a stroke.
Retrieves the type of shape used at the end of a stroke.
-The type of shape used at the end of a stroke.
Gets a value that specifies how the ends of each dash are drawn.
-A value that specifies how the ends of each dash are drawn.
Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-A positive number greater than or equal to 1.0f that describes the limit on the ratio of the miter length to half the stroke's thickness.
Retrieves the type of joint used at the vertices of a shape's outline.
-A value that specifies the type of joint used at the vertices of a shape's outline.
Retrieves a value that specifies how far in the dash sequence the stroke will start.
-A value that specifies how far in the dash sequence the stroke will start.
Gets a value that describes the stroke's dash pattern.
-A value that describes the predefined dash pattern used, or
If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-The number of entries in the dashes array if the stroke is dashed; otherwise, 0.
Copies the dash pattern to the specified array.
-A reference to an array that will receive the dash pattern. The array must be able to contain at least as many elements as specified by dashesCount. You must allocate storage for this array.
The number of dashes to copy. If this value is less than the number of dashes in the stroke style's dashes array, the returned dashes are truncated to dashesCount. If this value is greater than the number of dashes in the stroke style's dashes array, the extra dashes are set to 0.0f. To obtain the actual number of dashes in the stroke style's dashes array, use the GetDashesCount method.
The dashes are specified in units that are a multiple of the stroke width, with subsequent members of the array indicating the dashes and gaps between dashes: the first entry indicates a filled dash, the second a gap, and so on.
-Retrieves the type of shape used at the beginning of a stroke.
-Retrieves the type of shape used at the end of a stroke.
-Gets a value that specifies how the ends of each dash are drawn.
-Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-Retrieves the type of joint used at the vertices of a shape's outline.
-Retrieves a value that specifies how far in the dash sequence the stroke will start.
-Gets a value that describes the stroke's dash pattern.
-If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-Populates an
Populates an
Copies the specified triangles to the sink.
-An array of
The number of triangles to copy from the triangles array.
Closes the sink and returns its error status.
-If this method succeeds, it returns
Represents a geometry that has been transformed.
-Using an
To create an
Direct2D geometries are immutable and device-independent resources created by
Retrieves the source geometry of this transformed geometry object.
-When this method returns, contains a reference to a reference to the source geometry for this transformed geometry object. This parameter is passed uninitialized.
Retrieves the matrix used to transform the
Retrieves the source geometry of this transformed geometry object.
-Retrieves the matrix used to transform the
Renders drawing instructions to a window.
-As is the case with other render targets, you must call BeginDraw before issuing drawing commands. After you've finished drawing, call EndDraw to indicate that drawing is finished and to release access to the buffer backing the render target. For
A hardware render target's back-buffer is the size specified by GetPixelSize. If EndDraw presents the buffer, this bitmap is stretched to cover the surface where it is presented: the entire client area of the window. This stretch is performed using bilinear filtering if the render target is rendering in hardware and using nearest-neighbor filtering if the rendering target is using software. (Typically, an application will call Resize to ensure the pixel size of the render target and the pixel size of the destination match, and no scaling is necessary, though this is not a requirement.)
In the case where a window straddles adapters, Direct2D ensures that the portion of the off-screen render target is copied from the adapter where rendering is occurring to the adapter that needs to display the contents. If the adapter a render target is on has been removed or the driver upgraded while the application is running, this is returned as an error in the EndDraw call. In this case, the application should create a new render target and resources as necessary. -
CreatingTo create an
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Indicates whether the
A value that indicates whether the
Note??If the window was occluded the last time that EndDraw was called, the next time that the render target calls CheckWindowState, it will return
After this method is called, the contents of the render target's back-buffer are not defined, even if the
Returns the
The
Returns the
Describes an elliptical arc between two points.
-The end point of the arc.
The x-radius and y-radius of the arc.
A value that specifies how many degrees in the clockwise direction the ellipse is rotated relative to the current coordinate system.
A value that specifies whether the arc sweep is clockwise or counterclockwise.
A value that specifies whether the given arc is larger than 180 degrees.
Represents a cubic bezier segment drawn between two points.
-A cubic Bezier curve is defined by four points: a start point, an end point (point3), and two control points (point1 and point2). A Bezier segment does not contain a property for the starting point of the curve; it defines only the end point. The beginning point of the curve is the current point of the path to which the Bezier curve is added.
The two control points of a cubic Bezier curve behave like magnets, attracting portions of what would otherwise be a straight line toward themselves and producing a curve. The first control point, point1, affects the beginning portion of the curve; the second control point, point2, affects the ending portion of the curve.
Note??The curve doesn't necessarily pass through either of the control points; each control point moves its portion of the line toward itself, but not through itself.
-The first control point for the Bezier segment.
The second control point for the Bezier segment.
The end point for the Bezier segment.
Describes the extend modes and the interpolation mode of an
Describes the opacity and transformation of a brush.
-This structure is used when creating a brush. For convenience, Direct2D provides the D2D1::BrushProperties function for creating
After creating a brush, you can change its opacity or transform by calling the SetOpacity or SetTransform methods.
-A value between 0.0f and 1.0f, inclusive, that specifies the degree of opacity of the brush.
The transformation that is applied to the brush.
Describes the drawing state of a render target.
-The antialiasing mode for subsequent nontext drawing operations.
The antialiasing mode for subsequent text and glyph drawing operations.
A label for subsequent drawing operations.
A label for subsequent drawing operations.
The transformation to apply to subsequent drawing operations.
Contains the debugging level of an
To enable debugging, you must install the Direct2D Debug Layer.
-Contains the position and color of a gradient stop.
-Gradient stops can be specified in any order if they are at different positions. Two stops may share a position. In this case, the first stop specified is treated as the "low" stop (nearer 0.0f) and subsequent stops are treated as "higher" (nearer 1.0f). This behavior is useful if a caller wants an instant transition in the middle of a stop.
Typically, there are at least two points in a collection, although creation with only one stop is permitted. For example, one point is at position 0.0f, another point is at position 1.0f, and additional points are distributed in the [0, 1] range. Where the gradient progression is beyond the range of [0, 1], the stops are stored, but may affect the gradient.
When drawn, the [0, 1] range of positions is mapped to the brush, in a brush-dependent way. For details, see
Gradient stops with a position outside the [0, 1] range cannot be seen explicitly, but they can still affect the colors produced in the [0, 1] range. For example, a two-stop gradient 0.0f, Black}, {2.0f, White is indistinguishable visually from 0.0f, Black}, {1.0f, Mid-level gray. Also, the colors are clamped before interpolation.
-A value that indicates the relative position of the gradient stop in the brush. This value must be in the [0.0f, 1.0f] range if the gradient stop is to be seen explicitly.
The color of the gradient stop.
Contains the
Use this structure when you call the CreateHwndRenderTarget method to create a new
For convenience, Direct2D provides the D2D1::HwndRenderTargetProperties function for creating new
Contains the starting point and endpoint of the gradient axis for an
Use this method when creating new
The following illustration shows how a linear gradient changes as you change its start and end points. For the first gradient, the start point is set to (0,0) and the end point to (150, 50); this creates a diagonal gradient that starts at the upper-left corner and extends to the lower-right corner of the area being painted. When you set the start point to (0, 25) and the end point to (150, 25), a horizontal gradient is created. Similarly, setting the start point to (75, 0) and the end point to (75, 50) creates a vertical gradient. Setting the start point to (0, 50) and the end point to (150, 0) creates a diagonal gradient that starts at the lower-left corner and extends to the upper-right corner of the area being painted.
-Contains the data format and alpha mode for a bitmap or render target.
-For more information about the pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
-A value that specifies the size and arrangement of channels in each pixel.
A value that specifies whether the alpha channel is using pre-multiplied alpha, straight alpha, whether it should be ignored and considered opaque, or whether it is unkown.
Contains the control point and end point for a quadratic Bezier segment.
-The control point of the quadratic Bezier segment.
The end point of the quadratic Bezier segment.
Contains the gradient origin offset and the size and position of the gradient ellipse for an
Different values for center, gradientOriginOffset, radiusX and/or radiusY produce different gradients. The following illustration shows several radial gradients that have different gradient origin offsets, creating the appearance of the light illuminating the circles from different angles.
For convenience, Direct2D provides the D2D1::RadialGradientBrushProperties function for creating new D2D1_RADIAL_GRADIENT_BRUSH structures.
-Contains rendering options (hardware or software), pixel format, DPI information, remoting options, and Direct3D support requirements for a render target.
-Use this structure when creating a render target, or use it with the
As a convenience, Direct2D provides the D2D1::RenderTargetProperties helper function for creating
Not all render targets support hardware rendering. For a list, see the Render Targets Overview.
Using Default DPI SettingsTo use the default DPI, set dpiX and dpiY to 0. The default DPI varies depending on the render target:
To use the default DPI setting, both dpiX and dpiY must be set to 0. Setting only one value to 0 causes an E_INVALIDARG error when attempting to create a render target.
-A value that specifies whether the render target should force hardware or software rendering. A value of
The pixel format and alpha mode of the render target. You can use the D2D1::PixelFormat function to create a pixel format that specifies that Direct2D should select the pixel format and alpha mode for you. For a list of pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
The horizontal DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
The vertical DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
A value that specifies how the render target is remoted and whether it should be GDI-compatible. Set to
A value that specifies the minimum Direct3D feature level required for hardware rendering. If the specified minimum level is not available, the render target uses software rendering if the type member is set to
Contains the dimensions and corner radii of a rounded rectangle.
-Each corner of the rectangle specified by the rect is replaced with a quarter ellipse, with a radius in each direction specified by radiusX and radiusY.
If the radiusX is greater than or equal to half the width of the rectangle, and the radiusY is greater than or equal to one-half the height, the rounded rectangle is an ellipse with the same width and height of the rect.
Even when both radiuX and radiusY are zero, the rounded rectangle is different from a rectangle., When stroked, the corners of the rounded rectangle are roundly joined, not mitered (square).
-The coordinates of the rectangle.
The x-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
The y-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
Describes the stroke that outlines a shape.
-The following illustration shows different dashOffset values for the same custom dash style.
-The cap applied to the start of all the open figures in a stroked geometry.
The cap applied to the end of all the open figures in a stroked geometry.
The shape at either end of each dash segment.
A value that describes how segments are joined. This value is ignored for a vertex if the segment flags specify that the segment should have a smooth join.
The limit of the thickness of the join on a mitered corner. This value is always treated as though it is greater than or equal to 1.0f.
A value that specifies whether the stroke has a dash pattern and, if so, the dash style.
A value that specifies an offset in the dash sequence. A positive dash offset value shifts the dash pattern, in units of stroke width, toward the start of the stroked geometry. A negative dash offset value shifts the dash pattern, in units of stroke width, toward the end of the stroked geometry.
Contains the three vertices that describe a triangle.
-The first vertex of a triangle.
The second vertex of a triangle.
The third vertex of a triangle.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a bitmap that can be used as a surface for an
Represents a bitmap that has been bound to an
To create a bitmap, use one of the following methods of the render target on which the bitmap will be drawn:
For information about the pixel formats supported by Direct2D bitmaps, see Supported Pixel Formats and Alpha Modes.
An
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a producer of pixels that can fill an arbitrary 2D plane.
-An
Images are evaluated lazily. If the type of image passed in is concrete, then the image can be directly sampled from. Other images can act only as a source of pixels and can produce content only as a result of calling
Represents a Direct2D drawing resource.
-Retrieves the factory associated with this resource.
-When this method returns, contains a reference to a reference to the factory that created this resource. This parameter is passed uninitialized.
Retrieves the factory associated with this resource.
-Returns the size, in device-independent pixels (DIPs), of the bitmap.
-The size, in DIPs, of the bitmap.
A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-The size, in pixels, of the bitmap.
Retrieves the pixel format and alpha mode of the bitmap.
-The pixel format and alpha mode of the bitmap.
Return the dots per inch (DPI) of the bitmap.
-The horizontal DPI of the image. You must allocate storage for this parameter.
The vertical DPI of the image. You must allocate storage for this parameter.
Copies the specified region from the specified bitmap into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The bitmap to copy from.
The area of bitmap to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Copies the specified region from the specified render target into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The render target that contains the region to copy.
The area of renderTarget to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
All clips and layers must be popped off of the render target before calling this method. The method returns
Copies the specified region from memory into the current bitmap.
-In the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The data to copy.
The stride, or pitch, of the source bitmap stored in srcData. The stride is the byte count of a scanline (one row of pixels in memory). The stride can be computed from the following formula: pixel width * bytes per pixel + memory padding.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion; the two bitmap formats should match.
If this method is passed invalid input (such as an invalid destination rectangle), can produce unpredictable results, such as a distorted image or device failure.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Returns the size, in device-independent pixels (DIPs), of the bitmap.
-A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
-Retrieves the pixel format and alpha mode of the bitmap.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the color context information associated with the bitmap.
-When this method returns, contains the address of a reference to the color context interface associated with the bitmap.
If the bitmap was created without specifying a color context, the returned context is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the options used in creating the bitmap.
-This method returns the options used.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets either the surface that was specified when the bitmap was created, or the default surface created when the bitmap was created.
-The underlying DXGI surface for the bitmap.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| Cannot draw with a bitmap that is currently bound as the target bitmap. |
?
The bitmap used must have been created from a DXGI surface render target, a derived render target, or a device context created from an
The returned surface can be used with Microsoft Direct3D or any other API that interoperates with shared surfaces. The application must transitively ensure that the surface is usable on the Direct3D device that is used in this context. For example, if using the surface with Direct2D then the Direct2D render target must have been created through
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Maps the given bitmap into memory.
-The options used in mapping the bitmap into memory.
When this method returns, contains a reference to the rectangle that is mapped into memory.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | One or more arguments are not valid |
| D3DERR_DEVICELOST | The device has been lost but cannot be reset at this time. |
?
The bitmap must have been created with the
The caller should try to unmap the memory as quickly as is feasable to release occupied DMA aperture memory.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unmaps the bitmap from memory.
-The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | One or more arguments are not valid. |
| E_POINTER | Pointer is not valid. |
?
Any memory returned from the Map call is now invalid and may be reclaimed by the operating system or used for other purposes.
The bitmap must have been previously mapped.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the color context information associated with the bitmap.
-If the bitmap was created without specifying a color context, the returned context is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the options used in creating the bitmap.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets either the surface that was specified when the bitmap was created, or the default surface created when the bitmap was created.
-The bitmap used must have been created from a DXGI surface render target, a derived render target, or a device context created from an
The returned surface can be used with Microsoft Direct3D or any other API that interoperates with shared surfaces. The application must transitively ensure that the surface is usable on the Direct3D device that is used in this context. For example, if using the surface with Direct2D then the Direct2D render target must have been created through
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Paints an area with a bitmap.
-Paints an area with a bitmap.
-A bitmap brush is used to fill a geometry with a bitmap. Like all brushes, it defines an infinite plane of content. Because bitmaps are finite, the brush relies on an "extend mode" to determine how the plane is filled horizontally and vertically.
CreatingTo create a bitmap brush, use the
An
Defines an object that paints an area. Interfaces that derive from
An
Brush space in Direct2D is specified differently than in XPS and Windows Presentation Foundation (WPF). In Direct2D, brush space is not relative to the object being drawn, but rather is the current coordinate system of the render target, transformed by the brush transform, if present. To paint an object as it would be painted by a WPF brush, you must translate the brush space origin to the upper-left corner of the object's bounding box, and then scale the brush space so that the base tile fills the bounding box of the object.
For more information about brushes, see the Brushes Overview.
-Sets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Sets the transformation applied to the brush.
-The transformation to apply to this brush.
When you paint with a brush, it paints in the coordinate space of the render target. Brushes do not automatically position themselves to align with the object being painted; by default, they begin painting at the origin (0, 0) of the render target.
You can "move" the gradient defined by an
To align the content of an
The following illustrations show the effect of using an
The illustration on the right shows the result of transforming the
Gets the degree of opacity of this brush.
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Gets the transform applied to this brush.
-The transform applied to this brush.
When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Gets or sets the degree of opacity of this brush.
-Gets or sets the transform applied to this brush.
-When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
-Specifies how the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies how the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies the interpolation mode used when the brush bitmap is scaled or rotated.
-The interpolation mode used when the brush bitmap is scaled or rotated.
This method sets the interpolation mode for a bitmap, which is an enum value that is specified in the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, bilinear interpolation positions the bitmap more precisely to the application requests, but blurs the bitmap in the process.
-Specifies the bitmap source that this brush uses to paint.
-The bitmap source used by the brush.
This method specifies the bitmap source that this brush uses to paint. The bitmap is not resized or rescaled automatically to fit the geometry that it fills. The bitmap stays at its native size. To resize or translate the bitmap, use the SetTransform method to apply a transform to the brush.
The native size of a bitmap is the width and height in bitmap pixels, divided by the bitmap DPI. This native size forms the base tile of the brush. To tile a subregion of the bitmap, you must generate a new bitmap containing this subregion and use SetBitmap to apply it to the brush. -
-Gets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-A value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Like all brushes,
Gets the method by which the brush vertically tiles those areas that extend past its bitmap.
-A value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Like all brushes,
Gets the interpolation method used when the brush bitmap is scaled or rotated.
-The interpolation method used when the brush bitmap is scaled or rotated.
This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets the bitmap source that this brush uses to paint.
-When this method returns, contains the address to a reference to the bitmap with which this brush paints.
Gets or sets the method by which the brush horizontally tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the method by which the brush vertically tiles those areas that extend past its bitmap.
-Like all brushes,
Gets or sets the interpolation method used when the brush bitmap is scaled or rotated.
-This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
-Gets or sets the bitmap source that this brush uses to paint.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Paints an area with a bitmap.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Paints an area with a bitmap.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a bitmap that can be set as a target surface or have additional color context information specified.
-If the bitmap properties are not specified, the following information is assumed:
If the bitmap properties are specified, the bitmap properties will be used as follows:
The DXGI surface from which the bitmap can be created.
The bitmap properties specified in addition to the surface.
When this method returns, contains the address of a reference to a new bitmap object.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a sequence of commands that can be recorded and played back.
-The command list does not include static copies of resources with the recorded set of commands. All bitmaps, effects, and geometries are stored as references to the actual resource and all the brushes are stored by value. All the resource creation and destruction happens outside of the command list. The following table lists resources and how they are treated inside of a command list.
| Resource | How it is treated by the command list |
|---|---|
| Solid-color brush | Passed by value. |
| Bitmap brush | The brush is passed by value but the bitmap that is used to create the brush is in fact referenced. |
| Gradient brushes ? both linear and radial gradient | The brush is passed by value but the gradient stop collection itself is referenced. The gradient stop collection object is immutable. |
| Bitmaps | Passed by reference. |
| Drawing state block | The actual state on the device context is converted into set functions like set transform and is passed by value. |
| Geometry | Immutable object passed by value. |
| Stroke style | Immutable object passed by value. |
| Mesh | Immutable object passed by value. |
?
Using a CommandList as a TargetThe following pseudocode illustrates the different cases where a target is set as either a command list or as a bitmap.
//create a D2D device from an already created DXGI device
- The only way to retain vector content for later playback with full fidelity is to set the target type as a command list. When a bitmap is set as a target, any drawing on that target will get rasterized.
Using a CommandList to Create a BrushCommand lists are a good way to support pattern brushes, because they are capable of retaining fidelity on replay. The desired pattern can be stored as a command list, which can be used to create an image brush. This brush can then be used to paint paths.
The type of brush that supports filling a path with a command list is called an image brush.
The following psuedocode illustrates the process of using a command list with an image brush.
//Draw the pattern to the command list
- Because the brush accepts an image, it has the following other benefits as well:Compatible render targets are used very often for off-screen rendering to an intermediate bitmap that is later composited with the actual scene. Especially in the case of printing, using compatible render targets will increase the memory footprint because everything will be rasterized and sent to XPS instead of retaining the actual primitives. In this scenario, a developer is better off replacing the compatible render target with an intermediate command list. - The following pseudo code illustrates this point.
pD2D1Device->CreateDeviceContext(&pD2D1DeviceContext);
- pRenderTarget->CreateCompatibleRenderTarget(?, &pCompatibleRenderTarget); //render to the compatible render target
- pCompatibleRenderTarget->BeginDraw();
- RenderMyScene1(pCompatibleRenderTarget);
- pCompatibleRenderTarget->EndDraw(); //get the bitmap from the compatible render target
- pCompatibleRenderTarget->GetBitmap(pCompatBitmap); //draw this bitmap on the device context
- pD2D1DeviceContext->SetTarget(pTargetBitmap)
- pD2D1DeviceContext->BeginDraw();
- pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
- pD2D1DeviceContext->EndDraw(); //draw something else on the compatible render target
- pCompatibleRenderTarget->BeginDraw();
- pCompatibleRenderTarget->Clear();
- pCompatibleRenderTarget>RenderScene2();
- pCompatibleRenderTarget->EndDraw(); //get the bitmap from the compatible render target
- pCompatibleRenderTarget->GetBitmap(pCompatBitmap); //draw this bitmap on the device context
- pD2D1DeviceContext->SetTarget(pTargetBitmap)
- pD2D1DeviceContext->BeginDraw();
- pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
- pD2D1DeviceContext->EndDraw(); //Use a command list instead for better quality and performance //store the original target
- pOriginalTarget = pD2D1DeviceContext->GetTarget(); pD2D1DeviceContext->CreateCommandList(pCommandList1); //draw to command list 1
- pD2D1DeviceContext->SetTarget(pCommandList1);
- pD2D1DeviceContext->BeginDraw();
- RenderMyScene1(pD2D1DeviceContext);
- pD2D1DeviceContext->EndDraw(); //draw the command list to the original target
- pD2D1DeviceContext->SetTarget(pOriginalTarget);
- pD2D1DeviceContext->BeginDraw();
- pD2D1DeviceContext->DrawImage(pCommandList1);
- pD2D1DeviceContext->EndDraw(); pD2D1DeviceContext->CreateCommandList(pCommandList2); //draw something else to a new command list
- pD2D1DeviceContext->SetTarget(pCommandList2);
- pD2D1DeviceContext->BeginDraw();
- pD2D1DeviceContext->RenderScene2();
- pD2D1DeviceContext->EndDraw(); //draw the new command list on the old command list
- pD2D1DeviceContext->SetTarget(pCommandList1);
- pD2D1DeviceContext->BeginDraw();
- pD2D1DeviceContext->DrawImage(pCommandList2);
- pD2D1DeviceContext->EndDraw();
- Working with Other APIsDirect2D employs a simple model when interoperating with GDI and Direct3D/DXGI APIs. The command list does not record these commands. It instead rasterizes the contents in place and stores them as an
GDI: The command sink interface does not support Get/ReleaseDC() calls. When a call to ID2D1GdiInteropRenderTarget::ReleaseDC is made, Direct2D renders the contents of the updated region into a D2D1Bitmap. This will be replayed as an aliased DrawBitmap call with a copy composite mode. - To rasterize the bitmap at the correct DPI, at the time of playback of the commands, whatever DPI value is set using the SetDPI() function is used. This is the only case where the sink respects the SetDPI() call. -
DX: Direct3D cannot render directly to the command list. To render Direct3D content in this case, the application can call DrawBitmap with the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Streams the contents of the command list to the specified command sink.
-The sink into which the command list will be streamed.
If the method succeeds, it returns
Sample use:
Class MyCommandSink : public [This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Provides methods to allow a blend operation to be inserted into a transform graph.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents the set of transforms implemented by the effect-rendering system, which provides fixed-functionality.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes a node in a transform topology.
-Transform nodes are type-less and only define the notion of an object that accepts a number of inputs and is an output. This interface limits a topology to single output nodes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes a node in a transform topology.
-Transform nodes are type-less and only define the notion of an object that accepts a number of inputs and is an output. This interface limits a topology to single output nodes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of inputs to the transform node.
-This method returns the number of inputs to this transform node.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the properties of the output buffer of the specified transform node.
-The number of bits and the type of the output buffer.
The number of channels in the output buffer (1 or 4).
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | One or more arguments are not valid |
?
The available channel depth and precision depend on the capabilities of the underlying Microsoft Direct3D device.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets whether the output of the specified transform is cached.
-TRUE if the output should be cached; otherwise,
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Changes the blend description of the corresponding blend transform object.
-The new blend description specified for the blend transform.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the blend description of the corresponding blend transform object.
-When this method returns, contains the blend description specified for the blend transform.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the blend description of the corresponding blend transform object.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Extends the input rectangle to infinity using the specified clamp modes.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the extend mode in the x direction.
-The extend mode in the x direction.
If the extend mode enumeration is invalid, this operation is ignored and a debug message is traced.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the extend mode in the y direction.
-The extend mode in the y direction.
If the extend mode enumeration is invalid, this operation is ignored and a debug message is traced.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode in the x direction.
-This method returns the extend mode in the x direction.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode in the y direction.
-This method returns the extend mode in the y direction.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode in the x direction.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode in the y direction.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
A support transform for effects to modify the output rectangle of the previous effect or bitmap.
-The support transform can be used for two different reasons.
To indicate that a region of its input image is already transparent black.
This can increase efficiency for rendering bitmaps.
To increase the size of the input image.
?
?
Build date: 3/7/2012
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
A support transform for effects to modify the output rectangle of the previous effect or bitmap.
-The support transform can be used for two different reasons.
To indicate that a region of its input image is already transparent black.
This can increase efficiency for rendering bitmaps.
To increase the size of the input image.
?
?
Build date: 3/7/2012
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a color context that can be used with an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the size of the color profile associated with the bitmap.
-This method returns the size of the profile in bytes.
This can be used to allocate a buffer to receive the color profile bytes associated with the context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the color profile bytes for an
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| D2DERR_INSUFFICIENT_BUFFER | The supplied buffer was too small to accomodate the data. |
?
If profileSize is insufficient to store the entire profile, profile is zero-initialized before this method fails.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the size of the color profile associated with the bitmap.
-This can be used to allocate a buffer to receive the color profile bytes associated with the context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Establishes or changes the constant buffer data that will be passed to the compute shader specified for the render pass.
- If this call fails, the corresponding
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes the render information common to all of the various transform implementations.
-This interface is used by a transform implementation to first describe and then indicate changes to the rendering pass that corresponds to the transform.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets how a specific input to the transform should be handled by the renderer in terms of level of detail caching and filtering.
-The index of the input that will have the input description applied.
The description of the input to be applied to the transform.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
The input description must be matched correctly by the effect shader code.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows a caller to control the output precision and channel-depth of this stage in the rendering pipeline.
-The type of buffer that should be used as an output from this transform.
The number of channels that will be used on the output buffer.
If the method succeeds, it returns
If the output precision of the transform is not specified, then it will default to the precision specified on the Direct2D device context. If the default precision on the context is not specified, then the output precision will be the maximum of the precision of the inputs. The maximum of 16bpc UNORM and 16bpc FLOAT is 32bpc FLOAT.
Similar rules apply to the channel depth. The output channel depth will match the maximum of the input channel depths if the channel depth is
There is no global output channel depth; this is always left to the control of the transforms.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies that the output of the transform in which the render information is encapsulated is or is not cached.
-TRUE if the output of the transform is cached; otherwise,
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Provides an estimated hint of shader execution cost to D2D.
-An approximate instruction count of the associated shader.
The instruction count may be set according to the number of instructions in the shader. This information is used as a hint when rendering extremely large images. Calling this API is optional, but it may improve performance if you provide an accurate number.
Note??Instructions that occur in a loop should be counted according to the number of loop iterations.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies that the output of the transform in which the render information is encapsulated is or is not cached.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Provides an estimated hint of shader execution cost to D2D.
-The instruction count may be set according to the number of instructions in the shader. This information is used as a hint when rendering extremely large images. Calling this API is optional, but it may improve performance if you provide an accurate number.
Note??Instructions that occur in a loop should be counted according to the number of loop iterations.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Supplies data to an analysis effect.
- This interface can be implemented by either an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Supplies the analysis data to an analysis transform.
-The data that the transform will analyze.
The size of the analysis data.
If the method succeeds, it returns
The output of the transform will be copied to CPU-accessible memory by the imaging effects system before being passed to the implementation.
If this call fails, the corresponding
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a command sink.
-The
The
Not all methods implemented by
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a command sink.
-The
The
Not all methods implemented by
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Notifies the implementation of the command sink that drawing is about to commence.
- This method always returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates when
If the method/function succeeds, it returns
The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the antialiasing mode that will be used to render any subsequent geometry.
-The antialiasing mode selected for the command list.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the tags that correspond to the tags in the command sink.
-The first tag to associate with the primitive.
The second tag to associate with the primitive.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates the new default antialiasing mode for text.
-The antialiasing mode for the text.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates more detailed text rendering parameters.
-The parameters to use for text rendering.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets a new transform.
-The transform to be set.
If the method succeeds, it returns
The transform will be applied to the corresponding device context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets a new primitive blend mode.
-The primitive blend that will apply to subsequent primitives.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets how subsequent units are to be interpreted.
-The enumeration that specifies how units are to be interpreted.
If the method succeeds, it returns
The unit mode changes the interpretation of units from device-independent pixels (DIPs) to pixels or vice versa.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Clears the drawing area to the specified color.
-The color to which the command sink should be cleared.
If the method succeeds, it returns
The clear color is restricted by the currently selected clip and layer bounds.
If no color is specified, the color should be interpreted by context. Examples include but are not limited to:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates the glyphs to be drawn.
-The sequence of glyphs to be sent.
Additional non-rendering information about the glyphs.
The brush used to fill the glyphs.
The measuring mode to apply to the glyphs.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Draws a line drawn between two points.
-The start point of the line.
The end point of the line.
The brush used to fill the line.
The width of the stroke to fill the line.
The style of the stroke. If not specified, the stroke is solid.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates the geometry to be drawn to the command sink.
-The geometry to be stroked.
The brush that will be used to fill the stroked geometry.
The width of the stroke.
The style of the stroke.
An
You must convert ellipses and rounded rectangles to the corresponding ellipse and rounded rectangle geometries before calling into the DrawGeometry method.
Additional References| Minimum supported operating system | Same as Interface / Class |
| Highest IRQL level | N/A (user mode) |
| Callable from DlllMain() | No |
| Callable from services and session 0 | Yes |
| Callable from UI thread | Yes |
?
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Draws a rectangle.
-The rectangle to be drawn to the command sink.
The brush used to stroke the geometry.
The width of the stroke.
The style of the stroke.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Draws a bitmap to the render target.
-The bitmap to draw.
The destination rectangle. The default is the size of the bitmap and the location is the upper left corner of the render target.
The opacity of the bitmap.
The interpolation mode to use.
An optional source rectangle.
An optional perspective transform.
This method does not return a value.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Draws the provided image to the command sink.
-The image to be drawn to the command sink.
This defines the offset in the destination space that the image will be rendered to. The entire logical extent of the image will be rendered to the corresponding destination. If not specified, the destination origin will be (0, 0). The top-left corner of the image will be mapped to the target offset. This will not necessarily be the origin.
The corresponding rectangle in the image space will be mapped to the provided origins when processing the image.
If specified, the composite mode that will be applied to the limits of the currently selected clip.
If the method succeeds, it returns
Because the image can itself be a command list or contain an effect graph that in turn contains a command list, this method can result in recursive processing.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates a mesh to be filled by the command sink.
-The mesh object to be filled.
The brush with which to fill the mesh.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Fills an opacity mask on the command sink.
-The bitmap whose alpha channel will be sampled to define the opacity mask.
The brush with which to fill the mask.
The destination rectangle in which to fill the mask. If not specified, this is the origin.
The source rectangle within the opacity mask. If not specified, this is the entire mask.
If the method succeeds, it returns
The opacity mask bitmap must be considered to be clamped on each axis.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates to the command sink a geometry to be filled.
-The geometry that should be filled.
The primary brush used to fill the geometry.
A brush whose alpha channel is used to modify the opacity of the primary fill brush.
If the method succeeds, it returns
If the opacity brush is specified, the primary brush will be a bitmap brush fixed on both the x-axis and the y-axis.
Ellipses and rounded rectangles are converted to the corresponding geometry before being passed to FillGeometry.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Indicates to the command sink a rectangle to be filled.
-The rectangle to fill.
The brush with which to fill the rectangle.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Pushes a clipping rectangle onto the clip and layer stack.
-The rectangle that defines the clip.
Whether the given clip should be antialiased.
If the method succeeds, it returns
If the current world transform is not preserving the axis, clipRectangle is transformed and the bounds of the transformed rectangle are used instead.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Pushes a layer onto the clip and layer stack.
-The parameters that define the layer.
The layer resource to be used for rasterizing the layer.
If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Removes an axis-aligned clip from the layer and clip stack.
-If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Removes a layer from the layer and clip stack.
-If the method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a transform that uses a compute shader.
-The transform implements the normal Shatzis methods by implementing
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents the base interface for all of the transforms implemented by the transform author.
-Transforms are aggregated by effect authors. This interface provides a common interface for implementing the Shantzis rectangle calculations which is the basis for all the transform processing in Direct2D imaging extensions.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows a transform to state how it would map a rectangle requested on its output to a set of sample rectangles on its input.
-The output rectangle to which the inputs must be mapped.
The corresponding set of inputs. The inputs will directly correspond to the transform inputs.
The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.
The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The DirectImage renderer implementation reserves the right to call this method at any time and in any sequence.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Performs the inverse mapping to MapOutputRectToInputRects.
-The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.
The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The Direct2D renderer implementation reserves the right to call this method at any time and in any sequence.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a transform that uses a compute shader.
-The transform implements the normal Shatzis methods by implementing
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents the base interface for all of the transforms implemented by the transform author.
-Transforms are aggregated by effect authors. This interface provides a common interface for implementing the Shantzis rectangle calculations which is the basis for all the transform processing in Direct2D imaging extensions.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows a transform to state how it would map a rectangle requested on its output to a set of sample rectangles on its input.
-The output rectangle to which the inputs must be mapped.
The corresponding set of inputs. The inputs will directly correspond to the transform inputs.
The number of inputs specified. The implementation guarantees that this is equal to the number of inputs specified on the transform.
If the method succeeds, it returns
The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.
The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The DirectImage renderer implementation reserves the right to call this method at any time and in any sequence.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Performs the inverse mapping to MapOutputRectToInputRects.
-The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.
The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The Direct2D renderer implementation reserves the right to call this method at any time and in any sequence.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
This method allows a compute-shader?based transform to select the number of thread groups to execute based on the number of output pixels it needs to fill.
-The output rectangle that will be filled by the compute transform.
The number of threads in the x dimension.
The number of threads in the y dimension.
The number of threads in the z dimension.
If the method succeeds, it returns
If this call fails, the corresponding
Retrieves justification opportunity information for each of the glyphs given the text and shaping glyph properties.
-This function is called per-run, after shaping is done via the
Note??this function only supports natural metrics (
Analyzes various text properties for complex script processing such as bidirectional (bidi) support for languages like Arabic, determination of line break opportunities, glyph placement, and number substitution.
-Analyzes a text range for script boundaries, reading text attributes from the source and reporting the Unicode script ID to the sink callback SetScript.
-If this method succeeds, it returns
Analyzes a text range for script directionality, reading attributes from the source and reporting levels to the sink callback SetBidiLevel.
-If this method succeeds, it returns
While the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs. Otherwise, the returned levels may be wrong, because the Bidi algorithm is meant to apply to the paragraph as a whole.
-Analyzes a text range for spans where number substitution is applicable, reading attributes from the source and reporting substitutable ranges to the sink callback SetNumberSubstitution.
-If this method succeeds, it returns
Although the function can handle multiple ranges of differing number substitutions, the text ranges should not arbitrarily split the middle of numbers. Otherwise, it will treat the numbers separately and will not translate any intervening punctuation.
-Analyzes a text range for potential breakpoint opportunities, reading attributes from the source and reporting breakpoint opportunities to the sink callback SetLineBreakpoints.
-If this method succeeds, it returns
Although the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs, unless the specified text span is considered a whole unit. Otherwise, the returned properties for the first and last characters will inappropriately allow breaks.
-Parses the input text string and maps it to the set of glyphs and associated glyph data according to the font and the writing system's rendering rules.
-An array of characters to convert to glyphs.
The length of textString.
The font face that is the source of the output glyphs.
A Boolean flag set to TRUE if the text is intended to be drawn vertically.
A Boolean flag set to TRUE for right-to-left text.
A reference to a Script analysis result from an AnalyzeScript call.
The locale to use when selecting glyphs. For example the same character may map to different glyphs for ja-jp versus zh-chs. If this is
A reference to an optional number substitution which selects the appropriate glyphs for digits and related numeric characters, depending on the results obtained from AnalyzeNumberSubstitution. Passing
An array of references to the sets of typographic features to use in each feature range.
The length of each feature range, in characters. The sum of all lengths should be equal to textLength.
The number of feature ranges.
The maximum number of glyphs that can be returned.
When this method returns, contains the mapping from character ranges to glyph ranges.
When this method returns, contains a reference to an array of structures that contains shaping properties for each character.
The output glyph indices.
When this method returns, contains a reference to an array of structures that contain shaping properties for each output glyph.
When this method returns, contains the actual number of glyphs returned if the call succeeds.
If this method succeeds, it returns
Note that the mapping from characters to glyphs is, in general, many-to-many. The recommended estimate for the per-glyph output buffers is (3 * textLength / 2 + 16). This is not guaranteed to be sufficient. The value of the actualGlyphCount parameter is only valid if the call succeeds. In the event that maxGlyphCount is not big enough, HRESULT_FROM_WIN32(
Places glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
Place glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
-If this method succeeds, it returns
Analyzes a text range for script orientation, reading text and attributes from the source and reporting results to the sink.
-Source object to analyze.
Starting position within the source object.
Length to analyze.
Length to analyze.
If this method succeeds, it returns
Applies spacing between characters, properly adjusting glyph clusters and diacritics.
-The spacing before each character, in reading order.
The spacing after each character, in reading order.
The minimum advance of each character, to prevent characters from becoming too thin or zero-width. This must be zero or greater.
The length of the clustermap and original text.
The number of glyphs.
Mapping from character ranges to glyph ranges.
The advance width of each glyph.
The offset of the origin of each glyph.
Properties of each glyph, from GetGlyphs.
The new advance width of each glyph.
The new offset of the origin of each glyph.
If this method succeeds, it returns
The input and output advances/offsets are allowed to alias the same array.
-Retrieves the given baseline from the font.
-The font face to read.
A
Whether the baseline is vertical or horizontal.
Simulate the baseline if it is missing in the font.
Script analysis result from AnalyzeScript.
Note??You can pass an empty script analysis structure, like this
The language of the run.
The baseline coordinate value in design units.
Whether the returned baseline exists in the font.
If this method succeeds, it returns
If the baseline does not exist in the font, it is not considered an error, but the function will return exists = false. You may then use heuristics to calculate the missing base, or, if the flag simulationAllowed is true, the function will compute a reasonable approximation for you.
-Analyzes a text range for script orientation, reading text and attributes from the source and reporting results to the sink.
-Source object to analyze.
Starting position within the source object.
Length to analyze.
Length to analyze.
If this method succeeds, it returns
Returns 2x3 transform matrix for the respective angle to draw the glyph run.
-A
Whether the run's glyphs are sideways or not.
Returned transform.
If this method succeeds, it returns
The translation component of the transform returned is zero.
-Retrieves the properties for a given script.
-The script for a run of text returned from
A reference to a
Returns properties for the given script. If the script is invalid, it returns generic properties for the unknown script and E_INVALIDARG.
Determines the complexity of text, and whether you need to call
If this method succeeds, it returns
Text is not simple if the characters are part of a script that has complex shaping requirements, require bidi analysis, combine with other characters, reside in the supplementary planes, or have glyphs that participate in standard OpenType features. The length returned will not split combining marks from their base characters.
-Retrieves justification opportunity information for each of the glyphs given the text and shaping glyph properties.
-Font face that was used for shaping. This is mainly important for returning correct results of the kashida width.
May be
Font em size used for the glyph run.
Script of the text from the itemizer.
Length of the text.
Number of glyphs.
Characters used to produce the glyphs.
Clustermap produced from shaping.
Glyph properties produced from shaping.
A reference to a
If this method succeeds, it returns
This function is called per-run, after shaping is done via the
Note??this function only supports natural metrics (
Justifies an array of glyph advances to fit the line width.
-The line width.
The glyph count.
A reference to a
An array of glyph advances.
An array of glyph offsets.
The returned array of justified glyph advances.
The returned array of justified glyph offsets.
If this method succeeds, it returns
You call JustifyGlyphAdvances after you call
Fills in new glyphs for complex scripts where justification increased the advances of glyphs, such as Arabic with kashida.
-Font face used for shaping.
May be
Font em size used for the glyph run.
Script of the text from the itemizer.
Length of the text.
Number of glyphs.
Maximum number of output glyphs allocated by caller.
Clustermap produced from shaping.
Original glyphs produced from shaping.
Original glyph advances produced from shaping.
Justified glyph advances from
Justified glyph offsets from
Properties of each glyph, from
The new glyph count written to the modified arrays, or the needed glyph count if the size is not large enough.
Updated clustermap.
Updated glyphs with new glyphs inserted where needed.
Updated glyph advances.
Updated glyph offsets.
If this method succeeds, it returns
You call GetJustifiedGlyphs after the line has been justified, and it is per-run.
You should call GetJustifiedGlyphs if
Use GetJustifiedGlyphs mainly for cursive scripts like Arabic. If maxGlyphCount is not large enough, GetJustifiedGlyphs returns the error E_NOT_SUFFICIENT_BUFFER and fills the variable to which actualGlyphCount points with the needed glyph count.
-The interface you implement to provide needed information to the text analyzer, like the text and associated text properties.
Note?? If any of these callbacks return an error, the analysis functions will stop prematurely and return a callback error.
-Implemented by the text analyzer's client to provide text to the analyzer. It allows the separation between the logical view of text as a continuous stream of characters identifiable by unique text positions, and the actual memory layout of potentially discrete blocks of text in the client's backing store.
-If any of these callbacks returns an error, then the analysis functions will stop prematurely and return a callback error. Note that rather than return E_NOTIMPL, an application should stub the method and return a constant/null and
Used by the text analyzer to obtain the desired glyph orientation and resolved bidi level.
-The text position.
A reference to the text length.
A
A reference to the resolved bidi level.
Returning an error will abort the analysis.
The text analyzer calls back to this to get the desired glyph orientation and resolved bidi level, which it uses along with the script properties of the text to determine the actual orientation of each character, which it reports back to the client via the sink SetGlyphOrientation method.
-The text analyzer calls back to this to report the actual orientation of each character for shaping and drawing.
-This interface is implemented by the text analyzer's client to receive the output of a given text analysis.
-The text analyzer disregards any current state of the analysis sink, therefore, a Set method call on a range overwrites the previously set analysis result of the same range.
-The text analyzer calls back to this to report the actual orientation of each character for shaping and drawing.
-The starting position to report from.
Number of UTF-16 units of the reported range.
A
The adjusted bidi level to be used by the client layout for reordering runs. This will differ from the resolved bidi level retrieved from the source for cases such as Arabic stacked top-to-bottom, where the glyphs are still shaped as RTL, but the runs are TTB along with any CJK or Latin.
Whether the glyphs are rotated on their side, which is the default case for CJK and the case stacked Latin
Whether the script should be shaped as right-to-left. For Arabic stacked top-to-bottom, even when the adjusted bidi level is coerced to an even level, this will still be true.
Returns a successful code or an error code to abort analysis.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a range of vertices that are used when rendering less than the full contents of a vertex buffer.
-The first vertex in the range to process.
The number of vertices in the count to use.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes the options that transforms may set on input textures.
-The type of filter to apply to the input texture.
The mip level to retrieve from the upstream transform, if specified.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a CPU-based rasterization stage in the transform pipeline graph.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a CPU-based rasterization stage in the transform pipeline graph.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the render information for the transform.
-The interface supplied to the transform to allow specifying the precision-based transform pass.
If the method succeeds, it returns
Provides a render information interface to the source transform to allow it to specify state to the rendering system. This part of the render information interface is shared with the GPU transform.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Draws the transform to the graphics processing unit (GPU)?based Direct2D pipeline.
-The target to which the transform should be written.
The area within the source from which the image should be drawn.
The origin within the target bitmap to which the source data should be drawn.
If the method succeeds, it returns
The implementation of the rasterizer guarantees that adding the renderRect to the targetOrigin does not exceed the bounds of the bitmap.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Represents a single stage of a transform graph.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Represents a single stage of a transform graph.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
A specialized implementation of the Shantzis calculations to a transform implemented on the GPU. The information required to specify a ?Pass? in the rendering algorithm on a Pixel Shader is passed to the implementation through the SetDrawInfo method.
-Contains the content bounds, mask information, opacity settings, and other options for a layer resource.
-The content bounds of the layer. Content outside these bounds is not guaranteed to render.
The geometric mask specifies the area of the layer that is composited into the render target.
A value that specifies the antialiasing mode for the geometricMask.
A value that specifies the transform that is applied to the geometric mask when composing the layer.
An opacity value that is applied uniformly to all resources in the layer when compositing to the target.
A brush that is used to modify the opacity of the layer. The brush - is mapped to the layer, and the alpha channel of each mapped brush pixel is multiplied against the corresponding layer pixel.
A value that specifies whether the layer intends to render text with ClearType antialiasing.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a graph of transform nodes.
-This interface allows a graph of transform nodes to be specified. This interface is passed to
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets a single transform node as being equivalent to the whole graph.
-The node to be set.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
?
This equivalent to calling
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Adds the provided node to the transform graph.
-The node that will be added to the transform graph.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
?
This adds a transform node to the transform graph. A node must be added to the transform graph before it can be interconnected in any way. -
A transform graph cannot be directly added to another transform graph.
- Any other kind of interface derived from
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Removes the provided node from the transform graph.
-The node that will be removed from the transform graph.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| D2DERR_NOT_FOUND = (HRESULT_FROM_WIN32( | Direct2D could not locate the specified node. |
?
The node must already exist in the graph; otherwise, the call fails with D2DERR_NOT_FOUND.
Any connections to this node will be removed when the node is removed.
After the node is removed, it cannot be used by the interface until it has been added to the graph by AddNode.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the output node for the transform graph.
-The node that will be considered the output of the transform node.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| D2DERR_NOT_FOUND = (HRESULT_FROM_WIN32( | Direct2D could not locate the specified node. |
?
The node must already exist in the graph; otherwise, the call fails with D2DERR_NOT_FOUND.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Connects two nodes inside the transform graph.
-The node from which the connection will be made.
The node to which the connection will be made.
The node input that will be connected.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| D2DERR_NOT_FOUND = (HRESULT_FROM_WIN32( | Direct2D could not locate the specified node. |
?
Both nodes must already exist in the graph; otherwise, the call fails with D2DERR_NOT_FOUND.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Connects a transform node inside the graph to the corresponding effect input of the encapsulating effect.
-The effect input to which the transform node will be bound.
The node to which the connection will be made.
The node input that will be connected.
The method returns an
| Description | |
|---|---|
| No error occurred | |
| D2DERR_NOT_FOUND = (HRESULT_FROM_WIN32( | Direct2D could not locate the specified node. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Clears the transform nodes and all connections from the transform graph.
-Used when enough changes to transfoms would make editing of the transform graph inefficient.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes a graphics processing unit (GPU) rendering pass on a vertex or pixel shader.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
This interface is used to describe a GPU rendering pass on a vertex or pixel shader. It is passed to
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Indicates how pixel shader sampling will be restricted.
-The pixel shader is not restricted in its sampling.
The pixel shader samples inputs only at the same scene coordinate as the output pixel and returns transparent black whenever the input pixels are also transparent black.
If the shader specifies
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets a vertex buffer, a corresponding vertex shader, and options to control how the vertices are to be handled by the Direct2D context.
-The vertex buffer. If this is cleared, the default vertex shader and mapping to the transform rectangles are used.
Options that influence how the renderer will interact with the vertex shader.
How the vertices will be blended with the output texture.
If specified, the set of vertices to use from the buffer.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | One or more arguments are not valid. |
?
The vertex shaders associated with the vertex buffer through the vertex shader
If this call fails, the corresponding
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes features of an effect.
-Note??The caller should not rely heavily on the input rectangles returned by this structure. They can change due to subtle changes in effect implementations and due to optimization changes in the effect rendering system.
-The effect whose input connection is being specified.
The input index of the effect that is being considered.
The amount of data that would be available on the input. This can be used to query this information when the data is not yet available.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
A description of a single element to the vertex layout.
-This structure is a subset of
If the D2D1_APPEND_ALIGNED_ELEMENT constant is used for alignedByteOffset, the elements will be packed contiguously for convenience. -
-The HLSL semantic associated with this element in a shader input-signature.
The semantic index for the element. A semantic index modifies a semantic, with an integer index number. A semantic index is only needed in a case where there is more than one element with the same semantic. For example, a 4x4 matrix would have four components each with the semantic name matrix; however, each of the four components would have different semantic indices (0, 1, 2, and 3).
The data type of the element data.
An integer value that identifies the input-assembler. Valid values are between 0 and 15.
The offset in bytes between each element.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a mappable single-dimensional vertex buffer.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Maps the provided data into user memory.
-When this method returns, contains the address of a reference to the available buffer.
The desired size of the buffer.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
| D3DERR_DEVICELOST | The device has been lost but cannot be reset at this time. |
?
If data is larger than bufferSize, this method fails.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unmaps the vertex buffer.
-The method returns an
| Description | |
|---|---|
| No error occurred. | |
| The object was not in the correct state to process the method. |
?
After this method returns, the mapped memory from the vertex buffer is no longer accessible by the effect.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines the properties of a vertex buffer that are standard for all vertex shader definitions.
-If usage is dynamic, the system might return a system memory buffer and copy these vertices into the rendering vertex buffer for each element.
If the initialization data is not specified, the buffer will be uninitialized.
-The number of inputs to the vertex shader.
Indicates how frequently the vertex buffer is likely to be updated.
The initial contents of the vertex buffer.
The size of the vertex buffer, in bytes.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines a vertex shader and the input element description to define the input layout. The combination is used to allow a custom vertex effect to create a custom vertex shader and pass it a custom layout.
-The vertex shader will be loaded by the CreateVertexBuffer call that accepts the vertex buffer properties.
This structure does not need to be specified if one of the standard vertex shaders is used.
-The unique ID of the vertex shader.
An array of input assembler stage data types.
The number of input elements in the vertex shader.
The vertex stride.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines a resource texture when the original resource texture is created.
-The extents of the resource table in each dimension.
The number of dimensions in the resource texture. This must be a number from 1 to 3.
The precision of the resource texture to create.
The number of channels in the resource texture.
Specifies how pixel values beyond the extent of the texture will be sampled, in every dimension.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Tracks a transform-created resource texture.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Updates the specific resource texture inside the specific range or box using the supplied data.
-The "left" extent of the updates if specified; if
The "right" extent of the updates if specified; if
The stride to advance through the input data, according to dimension.
The number of dimensions in the resource texture. This must match the number used to load the texture.
The data to be placed into the resource texture.
The size of the data buffer to be used to update the resource texture.
This method does not return a value.
The number of dimensions in the update must match those of the created texture.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Instructs the effect-rendering system to offset an input bitmap without inserting a rendering pass.
-Because a rendering pass is not required, the interface derives from a transform node. This allows it to be inserted into a graph but does not allow an output buffer to be specified.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the offset in the current offset transform.
-The new offset to apply to the offset transform.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the offset currently in the offset transform.
-The current transform offset.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates or finds the given resource texture, depending on whether a resource id is specified. It also optionally initializes the texture with the specified data.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the unit mapping that an effect will use for properties that could be in either dots per inch (dpi) or pixels.
-The dpi on the x-axis.
The dpi on the y-axis.
If the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
This indicates the maximum feature level from the provided list which is supported by the device. If none of the provided levels are supported, then this API fails with
The feature levels provided by the application.
The count of feature levels provided by the application
The maximum feature level from the featureLevels list which is supported by the D2D device.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a transform that extends its input infinitely in every direction based on the passed in extend mode.
-The extend mode in the X-axis direction.
The extend mode in the Y-axis direction.
The returned transform.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates and returns an offset transform.
-The offset amount.
When this method returns, contains the address of a reference to an offset transform object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
An offset transform is used to offset an input bitmap without having to insert a rendering pass. An offset transform is automatically inserted by an Affine transform if the transform evaluates to a pixel-aligned transform.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Loads the given shader by its unique ID. Loading the shader multiple times is ignored. When the shader is loaded it is also handed to the driver to JIT, if it hasn?t been already. This can?t replace a shader, in order to do this a new
The unique id that identifies the shader.
The buffer that contains the shader to register.
The size of the shader buffer in bytes.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Loads the given shader by its unique ID. Loading the shader multiple times is ignored. When the shader is loaded it is also handed to the driver to JIT, if it hasn?t been already. This can?t replace a shader, in order to do this a new
The unique id that identifies the shader.
The buffer that contains the shader to register.
The size of the shader buffer in bytes.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Loads the given shader by its unique ID. Loading the shader multiple times is ignored. When the shader is loaded it is also handed to the driver to JIT, if it hasn?t been already. This can?t replace a shader, in order to do this a new
The unique id that identifies the shader.
The buffer that contains the shader to register.
The size of the shader buffer in bytes.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates or finds the given resource texture, depending on whether a resource id is specified. It also optionally initializes the texture with the specified data.
-The unique id that identifies the lookup table.
The properties used to create the resource texture.
The data to be loaded into the resource texture.
The size, in bytes, of the data.
The returned texture that can be used as a resource in a Direct2D effect.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a vertex buffer or finds a standard vertex buffer and optionally initializes it with vertices. The returned buffer can be specified in the render info to specify both a vertex shader and or to pass custom vertices to the standard vertex shader used by Direct2D.
-The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
This defines the feature for which support can be queried using
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Indicates whether the buffer precision is supported by the underlying Direct2D device.
-Returns TRUE if the buffer precision is supported. Returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows the internal context to be specified by the effect author.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Allows the internal context to be specified by the effect author.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates any resources used repeatedly during subsequent rendering calls.
-An internal factory interface that creates and returns effect author?centric types.
If the method succeeds, it returns
This moves resource creation cost to the CreateEffect call, rather than during rendering.
If the implementation fails this call, the corresponding
The following example shows an effect implementing an initialize method.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Prepares an effect for the rendering process.
-Indicates the type of change the effect should expect.
If the method succeeds, it returns
This method is called by the renderer when the effect is within an effect graph that is drawn.
The method will be called:
The method will not otherwise be called. The transforms created by the effect will be called to handle their input and output rectangles for every draw call.
Most effects defer creating any resources or specifying a topology until this call is made. They store their properties and map them to a concrete set of rendering techniques when first drawn.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a property binding to a pair of functions which get and set the corresponding property.
-The propertyName is used to cross-correlate the property binding with the registration XML. The propertyName must be present in the XML call or the registration will fail. The property index is used to define the index of the exposed property regardless of the order of the entries in the property binding array or the order of the properties in the registration XML. While the property indices must be contiguous, they do not have to be ordered. All properties must be bound.
-The name of the property. This must exist in the XML schema.
The index of the property.
The function that will receive the data to set.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Represents the drawing state of a render target: the antialiasing mode, transform, tags, and text-rendering options.
Note??You can get an
Represents the drawing state of a render target: the antialiasing mode, transform, tags, and text-rendering options.
-To create an
A drawing state block is a device-independent resource; you can create it once and retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the antialiasing mode, transform, and tags portion of the drawing state.
-When this method returns, contains the antialiasing mode, transform, and tags portion of the drawing state. You must allocate storage for this parameter.
Specifies the antialiasing mode, transform, and tags portion of the drawing state.
-The antialiasing mode, transform, and tags portion of the drawing state.
Specifies the text-rendering configuration of the drawing state.
-The text-rendering configuration of the drawing state, or
Retrieves the text-rendering configuration of the drawing state.
-When this method returns, contains the address of a reference to an
Retrieves or sets the antialiasing mode, transform, and tags portion of the drawing state.
-Retrieves or sets the text-rendering configuration of the drawing state.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Reperesents a basic image-processing construct in Direct2D.
-An effect takes zero or more input images, and has an output image. The images that are input into and output from an effect are lazily evaluated. This definition is sufficient to allow an arbitrary graph of effects to be created from the application by feeding output images into the input image of the next effect in the chain.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the sub-properties of the provided property by index.
-If there are no sub-properties, subProperties will be
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of top-level properties.
-This method returns the number of custom (non-system) properties that can be accessed by the object.
This method returns the number of custom properties on the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the property name that corresponds to the given index.
-The index of the property for which the name is being returned.
When this method returns, contains the name being retrieved.
The number of characters in the name buffer.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| HRESULT_FROM_WIN32( | The supplied buffer was too small to accomodate the data. |
| The specified property does not exist. |
?
This method returns an empty string if index is invalid. If the method returns RESULT_FROM_WIN32(
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of characters for the given property name.
-The index of the property name to retrieve.
This method returns the size in characters of the name corresponding to the given property index, or zero if the property index does not exist.
The value returned by this method can be used to ensure that the buffer size for GetPropertyName is appropriate.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the
This method returns the type of the selected property.
If the property does not exist, the method returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the index corresponding to the given property name.
-The name of the property to retrieve.
The index of the corresponding property name.
If the property does not exist, this method returns D2D1_INVALID_PROPERTY_INDEX. This reserved value will never map to a valid index and will cause
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the named property to the given value.
-The name of the property to set.
The data to set.
The number of bytes in the data to set.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| The specified property does not exist. | |
| E_OUTOFMEMORY | Failed to allocate necessary memory. |
| D3DERR_OUT_OF_VIDEO_MEMORY | Failed to allocate required video memory. |
| E_INVALIDARG | One or more arguments are invalid. |
| E_FAIL | Unspecified failure. |
?
If the property does not exist, the request is ignored and the method returns
Any error not in the standard set returned by a property implementation will be mapped into the standard error range.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the corresponding property by index.
-The index of the property to set.
The data to set.
The number of bytes in the data to set.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| The specified property does not exist. | |
| E_OUTOFMEMORY | Failed to allocate necessary memory. |
| D3DERR_OUT_OF_VIDEO_MEMORY | Failed to allocate required video memory. |
| E_INVALIDARG | One or more arguments are invalid. |
| E_FAIL | Unspecified failure. |
?
If the property does not exist, the request is ignored and
Any error not in the standard set returned by a property implementation will be mapped into the standard error range.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the property value by name.
-The property name to get.
When this method returns, contains the buffer with the data value.
The number of bytes in the data to be retrieved.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| The specified property does not exist. | |
| E_OUTOFMEMORY | Failed to allocate necessary memory. |
| D3DERR_OUT_OF_VIDEO_MEMORY | Failed to allocate required video memory. |
| E_INVALIDARG | One or more arguments are invalid. |
| E_FAIL | Unspecified failure. |
?
If name does not exist, no information is retrieved.
Any error not in the standard set returned by a property implementation will be mapped into the standard error range.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the value of the specified property by index.
-The index of the property from which the data is to be obtained.
When this method returns, contains a reference to the data requested.
The number of bytes in the data to be retrieved.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| The specified property does not exist. | |
| E_OUTOFMEMORY | Failed to allocate necessary memory. |
| D3DERR_OUT_OF_VIDEO_MEMORY | Failed to allocate required video memory. |
| E_INVALIDARG | One or more arguments are invalid. |
| E_FAIL | Unspecified failure. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the size of the property value in bytes, using the property index.
-The index of the property.
This method returns size of the value in bytes, using the property index
This method returns zero if index does not exist.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the sub-properties of the provided property by index.
-The index of the sub-properties to be retrieved.
When this method returns, contains the address of a reference to the sub-properties.
If there are no sub-properties, subProperties will be
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of top-level properties.
-This method returns the number of custom properties on the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the given input image by index.
-The index of the image to set.
The input image to set.
Whether to invalidate the graph at the location of the effect input
If the input index is out of range, the input image is ignored.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the given input image by index.
-The index of the image to retrieve.
If the input index is out of range, the returned image will be
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of inputs to the effect.
-This method returns the number of inputs to the effect.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the output image from the effect.
-When this method returns, contains the address of a reference to the output image for the effect.
The output image can be set as an input to another effect, or can be directly passed into the
It is also possible to use QueryInterface to retreive the same output image.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of inputs to the effect.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the output image from the effect.
-The output image can be set as an input to another effect, or can be directly passed into the
It is also possible to use QueryInterface to retreive the same output image.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates Direct2D resources.
-The
Creates Direct2D resources.
-The
A factory defines a set of CreateResource methods that can produce the following drawing resources:
To create an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so, this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note that the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU, however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Forces the factory to refresh any system defaults that it might have changed since factory creation.
-If this method succeeds, it returns
You should call this method before calling the GetDesktopDpi method, to ensure that the system DPI is current.
-Retrieves the current desktop dots per inch (DPI). To refresh this value, call ReloadSystemMetrics.
-Use this method to obtain the system DPI when setting physical pixel values, such as when you specify the size of a window.
- Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Transforms the specified geometry and stores the result as an
If this method succeeds, it returns
Like other resources, a transformed geometry the inherits the resource space and threading policy of the factory that created it. This object is immutable.
When stroking a transformed geometry with the DrawGeometry method, the stroke width is not affected by the transform applied to the geometry. The stroke width is only affected by the world transform.
-Creates an empty
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a render target that renders to a Microsoft Windows Imaging Component (WIC) bitmap.
-The bitmap that receives the rendering output of the render target.
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
Your application should create render targets once and hold onto them for the life of the application or until the
Creates an
If this method succeeds, it returns
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the
Creates a render target that draws to a DirectX Graphics Infrastructure (DXGI) surface.
-The
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
To write to a Direct3D surface, you obtain an
A DXGI surface render target is a type of
The DXGI surface render target and the DXGI surface must use the same DXGI format. If you specify the DXGI_FORMAT_UNKOWN format when you create the render target, it will automatically use the surface's format.
The DXGI surface render target does not perform DXGI surface synchronization.
For more information about creating and using DXGI surface render targets, see the Direct2D and Direct3D Interoperability Overview.
To work with Direct2D, the Direct3D device that provides the
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Creates a render target that draws to a Windows Graphics Device Interface (GDI) device context.
-The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. To enable the device context (DC) render target to work with GDI, set the DXGI format to
When this method returns, dcRenderTarget contains the address of the reference to the
If this method succeeds, it returns
Before you can render with a DC render target, you must use the render target's BindDC method to associate it with a GDI DC. Do this for each different DC and whenever there is a change in the size of the area you want to draw to.
To enable the DC render target to work with GDI, set the render target's DXGI format to
Your application should create render targets once and hold on to them for the life of the application or until the render target's EndDraw method returns the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a device that represents a display adapter.
-The
The requested
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
| D3DERR_OUTOFVIDEOMEMORY | Direct3D does not have enough display memory to perform the operation. |
?
Each call to CreateDevice returns a unique
The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
It is valid to specify a dash array only if
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a new drawing state block, this can be used in subsequent SaveDrawingState and RestoreDrawingState operations on the render target.
-The drawing state description structure.
The DirectWrite rendering params interface.
The address of the newly created drawing state block.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a new GDI metafile.
-A stream object that has the metafile data.
The address of the newly created GDI metafile object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Registers an effect within the factory instance with the property XML specified as a stream.
-The identifier of the effect to be registered.
A list of the effect properties, types, and metadata.
An array of properties and methods.
This binds a property by name to a particular method implemented by the effect author to handle the property. The name must be found in the corresponding propertyXml.
The number of bindings in the binding array.
The static factory that is used to create the corresponding effect.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
Direct2D effects must define their properties at registration time via registration XML. An effect declares several required system properties, and can also declare custom properties. See Custom Effect Creation and Registration for more information about formatting the propertyXml parameter.
RegisterEffect is both atomic and reference counted. To unregister an effect, call UnregisterEffect with the classId of the effect.
Important??RegisterEffect does not hold a reference to the DLL or executable file in which the effect is contained. The application must independently make sure that the lifetime of the DLL or executable file completely contains all instances of each registered and created effect.
Aside from the built-in effects that are globally registered, this API registers effects only for this factory, derived device, and device context interfaces.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates Direct2D resources.
-The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unregisters an effect within the factory instance that corresponds to the classId provided.
-The identifier of the effect to be unregistered.
In order for the effect to be fully unloaded, you must call UnregisterEffect the same number of times that you have registered the effect.
The UnregisterEffect method unregisters only those effects that are registered on the same factory. It cannot be used to unregister a built-in effect.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Returns the class IDs of the currently registered effects and global effects on this factory.
-When this method returns, contains an array of effects.
The capacity of the effects array.
When this method returns, contains the number of effects copied into effects.
When this method returns, contains the number of effects currently registered in the system.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| HRESULT_FROM_WIN32( | effectsRegistered is larger than effectCount. |
?
The set of class IDs will be atomically returned by the API. The set will not be interrupted by other threads registering or unregistering effects.
If effectsRegistered is larger than effectCount, the supplied array will still be filled to capacity with the current set of registered effects. This method returns the CLSIDs for all global effects and all effects registered to this factory.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Retrieves the properties of an effect.
-The ID of the effect to retrieve properties from.
When this method returns, contains the address of a reference to the property interface that can be used to query the metadata of the effect.
The returned effect properties will have all the mutable properties for the effect set to a default of
This method cannot be used to return the properties for any effect not visible to
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a new device context from a Direct2D device.
-The options to be applied to the created device context.
When this method returns, contains the address of a reference to the new device context.
If the method succeeds, it returns
The new device context will not have a selected target bitmap. The caller must create and select a bitmap as the target surface of the context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a resource domain whose objects and device contexts can be used together.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets the maximum amount of texture memory Direct2D accumulates before it purges the image caches and cached texture allocations.
-The new maximum texture memory in bytes.
Note??Direct2D may exceed the maximum texture memory you set with this method for a single frame if necessary to render the frame.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets the maximum amount of texture memory to maintain before evicting caches.
-The maximum amount of texture memory in bytes.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Clears all of the rendering resources used by Direct2D.
-Discards only resources that haven't been used for greater than the specified time in milliseconds. The default is 0 milliseconds.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Sets the maximum amount of texture memory to maintain before evicting caches.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a set of state and command buffers that are used to render to a target bitmap.
-Any resource created from a device context can be shared with any other resource created from a device context when both contexts are created on the same device.
-Represents an object that can receive drawing commands. Interfaces that inherit from
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Creates a Direct2D bitmap from a reference to in-memory source data.
-The dimension of the bitmap to create in pixels.
A reference to the memory location of the image data, or
The byte count of each scanline, which is equal to (the image width in pixels ? the number of bytes per pixel) + memory padding. If srcData is
The pixel format and dots per inch (DPI) of the bitmap to create.
When this method returns, contains a reference to a reference to the new bitmap. This parameter is passed uninitialized.
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Before Direct2D can load a WIC bitmap, that bitmap must be converted to a supported pixel format and alpha mode. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.
-Creates an
If this method succeeds, it returns
The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.
Sharing anBy passing an
You may also use this method to reinterpret the data of an existing bitmap and specify a new DPI or alpha mode. For example, in the case of a bitmap atlas, an
When using a DXGI surface render target (an
Note also that the
For more information about interoperability with Direct3D, see the Direct2D and Direct3D Interoperability Overview.
Sharing anAn
To use an
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a layer resource that can be used with this render target and its compatible render targets.
-When the method returns, contains a reference to a reference to the new layer. This parameter is passed uninitialized.
If this method succeeds, it returns
The layer automatically resizes itself, as needed.
-Create a mesh that uses triangles to describe a shape.
-When this method returns, contains a reference to a reference to the new mesh.
If this method succeeds, it returns
To populate a mesh, use its Open method to obtain an
Draws a line between the specified points using the specified stroke style.
-The start point of the line, in device-independent pixels.
The end point of the line, in device-independent pixels.
The brush used to paint the line's stroke.
A value greater than or equal to 0.0f that specifies the width of the stroke. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.
The style of stroke to paint, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the
Draws the outline of a rectangle that has the specified dimensions and stroke style.
-The dimensions of the rectangle to draw, in device-independent pixels.
The brush used to paint the rectangle's stroke.
A value greater than or equal to 0.0f that specifies the width of the rectangle's stroke. The stroke is centered on the rectangle's outline.
The style of stroke to paint, or
When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the
Paints the interior of the specified rectangle.
-The dimension of the rectangle to paint, in device-independent pixels.
The brush used to paint the rectangle's interior.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the
Draws the outline of the specified rounded rectangle using the specified stroke style.
-The dimensions of the rounded rectangle to draw, in device-independent pixels.
The brush used to paint the rounded rectangle's outline.
The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.
The style of the rounded rectangle's stroke, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the
Paints the interior of the specified rounded rectangle.
-The dimensions of the rounded rectangle to paint, in device independent pixels.
The brush used to paint the interior of the rounded rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the
Draws the outline of the specified ellipse using the specified stroke style.
-The position and radius of the ellipse to draw, in device-independent pixels.
The brush used to paint the ellipse's outline.
The thickness of the ellipse's stroke. The stroke is centered on the ellipse's outline.
The style of stroke to apply to the ellipse's outline, or
The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the
Paints the interior of the specified ellipse.
-The position and radius, in device-independent pixels, of the ellipse to paint.
The brush used to paint the interior of the ellipse.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the
Draws the outline of the specified geometry using the specified stroke style.
-The geometry to draw.
The brush used to paint the geometry's stroke.
The thickness of the geometry's stroke. The stroke is centered on the geometry's outline.
The style of stroke to apply to the geometry's outline, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the
Paints the interior of the specified geometry.
-The geometry to paint.
The brush used to paint the geometry's interior.
The opacity mask to apply to the geometry, or
If the opacityBrush parameter is not
When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the
Paints the interior of the specified mesh.
-The mesh to paint.
The brush used to paint the mesh.
The current antialias mode of the render target must be
FillMesh does not expect a particular winding order for the triangles in the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the
For this method to work properly, the render target must be using the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the
Draws the specified bitmap after scaling it to the size of the specified rectangle.
-The bitmap to render.
The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn. If the rectangle is not well-ordered, nothing is drawn, but the render target does not enter an error state.
A value between 0.0f and 1.0f, inclusive, that specifies the opacity value to be applied to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. Default is 1.0f.
The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is
The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to draw;
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the
To draw text with Direct2D, use the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the
Draws the formatted text described by the specified
When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the
Draws the specified glyphs.
-The origin, in device-independent pixels, of the glyphs' baseline.
The glyphs to render.
The brush used to paint the specified glyphs.
A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the
Gets the current transform of the render target.
-When this returns, contains the current transform of the render target. This parameter is passed uninitialized.
Sets the antialiasing mode of the render target. The antialiasing mode applies to all subsequent drawing operations, excluding text and glyph drawing operations.
-The antialiasing mode for future drawing operations.
To specify the antialiasing mode for text and glyph operations, use the SetTextAntialiasMode method.
-Retrieves the current antialiasing mode for nontext drawing operations.
-The current antialiasing mode for nontext drawing operations.
Specifies the antialiasing mode to use for subsequent text and glyph drawing operations.
-The antialiasing mode to use for subsequent text and glyph drawing operations.
Gets the current antialiasing mode for text and glyph drawing operations.
-The current antialiasing mode for text and glyph drawing operations.
Specifies text rendering options to be applied to all subsequent text and glyph drawing operations.
-The text rendering options to be applied to all subsequent text and glyph drawing operations;
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the render target's current text rendering options.
-When this method returns, textRenderingParamscontains the address of a reference to the render target's current text rendering options.
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Specifies a label for subsequent drawing operations.
-A label to apply to subsequent drawing operations.
A label to apply to subsequent drawing operations.
The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.
-Gets the label for subsequent drawing operations.
-When this method returns, contains the first label for subsequent drawing operations. This parameter is passed uninitialized. If
When this method returns, contains the second label for subsequent drawing operations. This parameter is passed uninitialized. If
If the same address is passed for both parameters, both parameters receive the value of the second tag.
-Adds the specified layer to the render target so that it receives all subsequent drawing operations until PopLayer is called.
-The PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.
Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.
A particular
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the
Stops redirecting drawing operations to the layer that is specified by the last PushLayer call.
-A PopLayer must match a previous PushLayer call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the
Executes all pending drawing commands.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
This command does not flush the device that is associated with the render target.
Calling this method resets the error state of the render target.
-Saves the current drawing state to the specified
Sets the render target's drawing state to that of the specified
Specifies a rectangle to which all subsequent drawing operations are clipped.
-The size and position of the clipping area, in device-independent pixels.
The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.
The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.
The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.
Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.
Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.
After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.
The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.
Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.
The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.
A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the
Removes the last axis-aligned clip from the render target. After this method is called, the clip is no longer applied to subsequent drawing operations.
-A PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.
PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.
For an example, see How to Clip with an Axis-Aligned Clip Rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the
Clears the drawing area to the specified color.
-The color to which the drawing area is cleared.
Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is
If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.
-Initiates drawing on this render target.
-Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Ends drawing operations on the render target and indicates the current error state and associated tags.
-When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Retrieves the pixel format and alpha mode of the render target.
-The pixel format and alpha mode of the render target.
Sets the dots per inch (DPI) of the render target.
-A value greater than or equal to zero that specifies the horizontal DPI of the render target.
A value greater than or equal to zero that specifies the vertical DPI of the render target.
This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed.
For
Return the render target's dots per inch (DPI).
-When this method returns, contains the horizontal DPI of the render target. This parameter is passed uninitialized.
When this method returns, contains the vertical DPI of the render target. This parameter is passed uninitialized.
This method indicates the mapping from pixel space to device-independent space for the render target.
For
Returns the size of the render target in device-independent pixels.
-The current size of the render target in device-independent pixels.
Returns the size of the render target in device pixels.
-The size of the render target in device pixels.
Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-The maximum size, in pixels, of any one bitmap dimension supported by the render target.
Indicates whether the render target supports the specified properties.
-The render target properties to test.
TRUE if the specified render target properties are supported by this render target; otherwise,
This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.
-Gets or sets the current transform of the render target.
-Retrieves or sets the current antialiasing mode for nontext drawing operations.
-Gets or sets the current antialiasing mode for text and glyph drawing operations.
-Retrieves or sets the render target's current text rendering options.
-If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
-Retrieves the pixel format and alpha mode of the render target.
-Returns the size of the render target in device-independent pixels.
-Returns the size of the render target in device pixels.
-Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a bitmap that can be used as a target surface, for reading back to the CPU, or as a source for the DrawBitmap and
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
| D3DERR_OUTOFVIDEOMEMORY | Direct3D does not have enough display memory to perform the operation. |
?
The new bitmap can be used as a target for SetTarget if it is created with
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a Direct2D bitmap by copying a WIC bitmap.
-The WIC bitmap source to copy from.
A bitmap properties structure that specifies bitmap creation options.
The address of the newly created bitmap object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a color context.
-The space of color context to create.
A buffer containing the ICC profile bytes used to initialize the color context when space is
The size in bytes of Profile.
When this method returns, contains the address of a reference to a new color context object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
The new color context can be used in
When space is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a color context by loading it from the specified filename. The profile bytes are the contents of the file specified by Filename.
-The path to the file containing the profile bytes to initialize the color context with.
When this method returns, contains the address of a reference to a new color context.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
The new color context can be used in
,
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a color context from an
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
The new color context can be used in
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a bitmap that can be set as a target surface or have additional color context information specified.
-The DXGI surface from which the bitmap can be created.
The bitmap properties specified in addition to the surface.
When this method returns, contains the address of a reference to a new bitmap object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
| D3DERR_OUTOFVIDEOMEMORY | Direct3D does not have enough display memory to perform the operation. |
?
If the bitmap properties are not specified, the following information is assumed:
If the bitmap properties are specified, the bitmap properties will be used as follows:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an effect from a class ID.
-The class ID of the effect to create.
When this method returns, contains the address of a reference to a new effect.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
| D3DERR_OUTOFVIDEOMEMORY | Direct3D does not have enough display memory to perform the operation. |
| The specified effect is not registered by the system. | |
| The effect requires capabilities not supported by the D2D device. |
?
The created effect does not increment the reference count for the dynamic-link library (DLL) from which the effect was created. If the application deletes an effect while that effect is loaded, the resulting behavior is unpredictable.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a gradient stop collection, enabling the gradient to contain color channels with values outside of [0,1] and also enabling rendering to a high-color render target with interpolation in sRGB space.
-An array of color values and offsets.
The number of elements in the gradientStops array.
Specifies both the input color space and the space in which the color interpolation occurs.
The color space that colors will be converted to after interpolation occurs.
The precision of the texture used to hold interpolated values.
Defines how colors outside of the range defined by the stop collection are determined.
Defines how colors are interpolated. D2D1_COLOR_INTERPOLATION_MODE_PREMULTPLIED is the default, see Remarks for more info.
The new gradient stop collection.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
This method linearly interpolates between the color stops. An optional color space conversion is applied after interpolation. Whether and how this gamma conversion is applied is determined before and after interpolation. This method will fail if the device context does not support the requested buffer precision.
Color interpolation modes| Mode | Description |
|---|---|
| D2D1_COLOR_INTERPOLATION_MODE_PREMULTPLIED | The effect premultiplies stops are before interpolation and then un-premultiplies them before converting the color. |
| The stops are all left as straight alpha. |
?
Note??You must always specify colors in straight alpha, regardless of interpolation mode. The interpolation mode only affects the interpolated values.
Requirements| Minimum supported operating system | Same as Interface / Class |
| Highest IRQL level | N/A (user mode) |
| Callable from DlllMain() | No |
| Callable from services and session 0 | Yes |
| Callable from UI thread | Yes |
?
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an image brush with the given properties.
-The image to be used as a source for the image brush.
The properties specific to an image brush.
Properties common to all brushes.
When this method returns, contains the adress of a reference to the input rectangles.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
This sample illustrates drawing a rectangle with an image brush.
null ; pDeviceContext->GetTarget(&pOldTarget); null ; hr = pDeviceContext->CreateCommandList(&pCommandList); if (SUCCEEDED(hr)) { pDeviceContext->SetTarget(pCommandList); hr = RenderPatternToCommandList(pDeviceContext); } pDeviceContext->SetTarget(pOldTarget); null ; if (SUCCEEDED(hr)) { hr = pDeviceContext->CreateImageBrush( pCommandList, null , null , &pImageBrush); } // Fill a rectangle with the image brush. if (SUCCEEDED(hr)) { pDeviceContext->FillRectangle( D2D1::RectF(0, 0, 100, 100), pImageBrush); } SafeRelease(&pImageBrush); SafeRelease(&pCommandList); SafeRelease(&pOldTarget); return hr;
- }[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Creates a bitmap brush, the input image is a Direct2D bitmap object.
-The bitmap to use as the brush.
A bitmap brush properties structure.
A brush properties structure.
The address of the newly created bitmap brush object.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
?
A
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Indicates whether the format is supported by Direct2D.
-The DXGI format to check.
Returns TRUE if the format is supported. Returns
You can use supported formats in the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Indicates whether the buffer precision is supported by the underlying Direct2D device.
-Returns TRUE if the buffer precision is supported. Returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the local bounds of an image.
-The image whose bounds will be calculated.
When this method returns, contains a reference to the bounds of the image in device independent pixels (DIPs) and in local space.
The image bounds don't include multiplication by the world transform. They do reflect the current DPI, unit mode, and interpolation mode of the context. To get the bounds that include the world trasnfrom, use
The returned bounds reflect which pixels would be impacted by calling DrawImage with a target offset of (0,0) and an identity world transform matrix. -
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the world bounds of an image.
-The image whose bounds will be calculated.
When this method returns, contains a reference to the bounds of the image in device independent pixels (DIPs).
The image bounds reflect the current DPI, unit mode, interpolation mode, and world transform of the context. To get bounds which don't include the world transform, use
The returned bounds reflect which pixels would be impacted by calling DrawImage with the same image and a target offset of (0,0). They do not reflect the current clip rectangle set on the device context or the extent of the context?s current target image. -
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the world-space bounds in DIPs of the glyph run using the device context DPI. STDMETHOD(GetGlyphRunWorldBounds)( D2D1_POINT_2F baselineOrigin, _In_ CONST
The origin of the baseline for the glyph run.
The glyph run to to be measured.
The DirectWrite measuring mode.
The bounds of the glyph run.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the device associated with a device context.
-When this method returns, contains the address of a reference to a Direct2D device associated with this device context.
The application can retrieve the device even if it is created from an earlier render target code-path. The application must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the target for the device context.
-The surface or command list to which the Direct2D device context will render.
The target can be changed at any time, including while the context is drawing.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the target currently associated with the device context.
-When this method returns, contains the address of a reference to the target currently associated with the device context.
If a target is not associated with the device context, target will contain
If the currently selected target is a bitmap rather than a command list, the application can gain access to the initial bitmaps created by using one of the following methods:
It is not possible for an application to destroy these bitmaps. All of these bitmaps are bindable as bitmap targets. However not all of these bitmaps can be used as bitmap sources for
CreateDxgiSurfaceRenderTarget will create a bitmap that is usable as a bitmap source if the DXGI surface is bindable as a shader resource view.
CreateCompatibleRenderTarget will always create bitmaps that are usable as a bitmap source.
Direct2D will only lock bitmaps that are not currently locked.
Calling QueryInterface for ID2D1GdiInteropRenderTarget will always succeed. ID2D1GdiInteropRenderTarget::GetDC will return a device context corresponding to the currently bound target bitmap. GetDC will fail if the target bitmap was not created with the GDI_COMPATIBLE flag set.
Although the target can be a command list, it cannot be any other type of image. It cannot be the output image of an effect.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the rendering controls for the given device context.
-The rendering controls to be applied.
The rendering controls allow the application to tune the precision, performance, and resource usage of rendering operations.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rendering controls that have been applied to the context.
-When this method returns, contains a reference to the rendering controls for this context.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Changes the primitive blend mode that is used for all rendering operations in the device context.
-The primitive blend to use.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Returns the currently set primitive blend used by the device context.
-The current primitive blend. The default value is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets what units will be used to interpret values passed into the device context.
-An enumeration defining how passed-in units will be interpreted by the device context.
This method will affect all properties and parameters affected by SetDpi and GetDpi. This affects all coordinates, lengths, and other properties that are not explicitly defined as being in another unit. For example:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the mode that is being used to interpret values by the device context.
-The unit mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Draws a series of glyphs to the device context.
-Origin of first glyph in the series.
Glyph information including glyph indices, advances, and offsets.
Supplementary glyph series information.
The brush that defines the text color.
The measuring mode of the glyph series, used to determine the advances and offsets. The default value is
The glyphRunDescription is ignored when rendering, but can be useful for printing and serialization of rendering commands, such as to an XPS or SVG file. This extends
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Draws an image to the device context.
-The image to be drawn to the device context.
The offset in the destination space that the image will be rendered to. The entire logical extent of the image will be rendered to the corresponding destination. If not specified, the destination origin will be (0, 0). The top-left corner of the image will be mapped to the target offset. This will not necessarily be the origin. This default value is
The corresponding rectangle in the image space will be mapped to the given origins when processing the image. This default value is
The interpolation mode that will be used to scale the image if necessary. The default value is D2D1_IMAGE_INTERPOLATION_BILINEAR.
The composite mode that will be applied to the limits of the currently selected clip. The default value is D2D1_COMPOSITE_MODE_DEFAULT
If interpolationMode is D2D1_IMAGE_INTERPOLATION_MODE_HIGH_QUALITY, different scalers will be used depending on the scale factor implied by the world transform.
Any invalid rectangles accumulated on any effect that is drawn by this call will be discarded regardless of which portion of the image rectangle is drawn.
If compositeMode is D2D1_COMPOSITE_MODE_DEFAULT, DrawImage will use the currently selected primitive blend specified by
If there is an image rectangle and a world transform, this is equivalent to inserting a clip effect to represent the image rectangle and a 2D affine transform to take into account the world transform.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Draw a metafile to the device context.
-The metafile to draw.
The offset from the upper left corner of the render target.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Draws a bitmap to the render target.
-The bitmap to draw.
The destination rectangle. The default is the size of the bitmap and the location is the upper left corner of the render target.
The opacity of the bitmap.
The interpolation mode to use.
An optional source rectangle.
An optional perspective transform.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Push a layer on the device context.
-A layer parameters structure.
The layer to push on the device context.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
This indicates that a portion of an effect's input is invalid. This method can be called many times.
-The effect to invalidate.
The input indexl
The rect to invalidate.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the number of invalid output rectangles that have accumulated on the effect.
-The effect to count the invalid rectangles on.
The returned rectangle count.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the invalid rectangles that are at the output of the effect.
-The effect to get the invalid rectangles from.
An array of D2D1_RECT_F structures. You must allocate this to the correct size. You can get the count of the invalid rectangles using the GetEffectInvalidRectangleCount method.
The number of rectangles to get.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the maximum region of each specified input which would be used during a subsequent rendering operation.
-The effect to check the input rectangles against.
The rectangle of the render target image.
The input descriptions you provide.
The returned input rectangles.
The number of required input rectangles.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid parameter was passed to the returning function. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Fill using the alpha channel of the supplied opacity mask bitmap. The brush opacity will be modulated by the mask. The render target antialiasing mode must be set to aliased.
-The bitmap that acts as the opacity mask
The brush to use for filling the primitive.
The destination rectangle to output to in the render target
The source rectangle from the opacity mask bitmap.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the device associated with a device context.
-The application can retrieve the device even if it is created from an earlier render target code-path. The application must use an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the target currently associated with the device context.
-If a target is not associated with the device context, target will contain
If the currently selected target is a bitmap rather than a command list, the application can gain access to the initial bitmaps created by using one of the following methods:
It is not possible for an application to destroy these bitmaps. All of these bitmaps are bindable as bitmap targets. However not all of these bitmaps can be used as bitmap sources for
CreateDxgiSurfaceRenderTarget will create a bitmap that is usable as a bitmap source if the DXGI surface is bindable as a shader resource view.
CreateCompatibleRenderTarget will always create bitmaps that are usable as a bitmap source.
Direct2D will only lock bitmaps that are not currently locked.
Calling QueryInterface for ID2D1GdiInteropRenderTarget will always succeed. ID2D1GdiInteropRenderTarget::GetDC will return a device context corresponding to the currently bound target bitmap. GetDC will fail if the target bitmap was not created with the GDI_COMPATIBLE flag set.
Although the target can be a command list, it cannot be any other type of image. It cannot be the output image of an effect.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rendering controls that have been applied to the context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Returns the currently set primitive blend used by the device context.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the mode that is being used to interpret values by the device context.
-Specifies the identifiers of the metadata items in an 8BIM IPTC digest metadata block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_BLOB] The embedded IPTC digest value.
Specifies the identifiers of the metadata items in an 8BIM IPTC block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UNKNOWN] The IPTC block embedded in this 8BIM IPTC block.
Specifies the identifiers of the metadata items in an 8BIMResolutionInfo block.
-[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UI4] The horizontal resolution of the image.
[VT_UI2] The units that the horizontal resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image width is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
[VT_UI4] The vertical resolution of the image.
[VT_UI2] The units that the vertical resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image height is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
Specifies the desired alpha channel usage.
-Use alpha channel.
Use a pre-multiplied alpha channel.
Ignore alpha channel.
Specifies the desired cache usage.
-The CreateBitmap of the
Do not cache the bitmap.
Cache the bitmap when needed.
Cache the bitmap at initialization.
Specifies the capabilities of the decoder.
-Decoder recognizes the image was encoded with an encoder produced by the same vendor.
Decoder can decode all the images within an image container.
Decoder can decode some of the images within an image container.
Decoder can enumerate the metadata blocks within a container format.
Decoder can find and decode a thumbnail.
Specifies the type of dither algorithm to apply when converting between image formats.
-A solid color algorithm without dither.
A solid color algorithm without dither.
A 4x4 ordered dither algorithm.
An 8x8 ordered dither algorithm.
A 16x16 ordered dither algorithm.
A 4x4 spiral dither algorithm.
An 8x8 spiral dither algorithm.
A 4x4 dual spiral dither algorithm.
An 8x8 dual spiral dither algorithm.
An error diffusion algorithm.
Specifies the cache options available for an encoder.
-The encoder is cached in memory. This option is not supported.
The encoder is cached to a temporary file. This option is not supported.
The encoder is not cached.
Specifies the sampling or filtering mode to use when scaling an image.
-A nearest neighbor interpolation algorithm. Also known as nearest pixel or point interpolation.
The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.
A bilinear interpolation algorithm.
The output pixel values are computed as a weighted average of the nearest four pixels in a 2x2 grid.
A bicubic interpolation algorithm.
Destination pixel values are computed as a weighted average of the nearest sixteen pixels in a 4x4 grid.
A Fant resampling algorithm.
Destination pixel values are computed as a weighted average of the all the pixels that map to the new pixel.
Specifies access to an
Specifies the type of palette used for an indexed image format.
-An arbitrary custom palette provided by caller.
An optimal palette generated using a median-cut algorithm. Derived from the colors in an image.
A black and white palette.
A palette that has its 8-color on-off primaries and the 16 system colors added. With duplicates removed, 16 colors are available.
A palette that has 3 intensity levels of each primary: 27-color on-off primaries and the 16 system colors added. With duplicates removed, 35 colors are available.
A palette that has 4 intensity levels of each primary: 64-color on-off primaries and the 16 system colors added. With duplicates removed, 72 colors are available.
A palette that has 5 intensity levels of each primary: 125-color on-off primaries and the 16 system colors added. With duplicates removed, 133 colors are available.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as WICBitmapPaletteFixedHalftoneWeb.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as
A palette that has its 252-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has its 256-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has 4 shades of gray.
A palette that has 16 shades of gray.
A palette that has 256 shades of gray.
Specifies the flip and rotation transforms.
-A rotation of 0 degrees.
A clockwise rotation of 90 degrees.
A clockwise rotation of 180 degrees.
A clockwise rotation of 270 degrees.
A horizontal flip. Pixels are flipped around the vertical y-axis.
A vertical flip. Pixels are flipped around the horizontal x-axis.
Specifies the color context types.
-An uninitialized color context.
A color context profile.
An EXIF color space color context.
Specifies component enumeration options.
-Enumerate signed components.
Force a read of the registry when enumerating components.
Enumerate disabled components.
Enumerate unsigned components.
Enumerate only built in components.
Specifies the component signing status.
-A signed component.
An unsigned component
A component is safe.
Components that do not have a binary component to sign, such as a pixel format, should return this value.
A component has been disabled.
Specifies the type of Windows Imaging Component (WIC) component.
-A WIC decoder.
A WIC encoder.
A WIC pixel converter.
A WIC metadata reader.
A WIC metadata writer.
A WIC pixel format.
All WIC components.
Specifies decode options.
-Cache metadata when needed.
Cache metadata when decoder is loaded.
Specifies the application extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_UI1 | VT_VECTOR] Indicates a string that identifies the application.
[VT_UI1 | VT_VECTOR] Indicates data that is exposed by the application.
Specifies the comment extension metadata properties for a Graphics Interchange Format (GIF) image.
-[VT_LPSTR] Indicates the comment text.
Specifies the graphic control extension metadata properties that define the transitions between each frame animation for Graphics Interchange Format (GIF) images.
-[VT_UI1] Indicates the disposal requirements. 0 - no disposal, 1 - do not dispose, 2 - restore to background color, 3 - restore to previous.
[VT_BOOL] Indicates the user input flag. TRUE if user input should advance to the next frame; otherwise,
[VT_BOOL] Indicates the transparency flag. TRUE if a transparent color in is in the color table for this frame; otherwise,
[VT_UI2] Indicates how long to display the next frame before advancing to the next frame, in units of 1/100th of a second.
[VT_UI1] Indicates which color in the palette should be treated as transparent.
Specifies the image descriptor metadata properties for Graphics Interchange Format (GIF) frames.
-[VT_UI2] Indicates the X offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates the Y offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates width of this frame, in pixels.
[VT_UI2] Indicates height of this frame, in pixels.
[VT_BOOL] Indicates the local color table flag. TRUE if global color table is present; otherwise,
[VT_BOOL] Indicates the interlace flag. TRUE if image is interlaced; otherwise,
[VT_BOOL] Indicates the sorted color table flag. TRUE if the color table is sorted from most frequently to least frequently used color; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
Specifies the logical screen descriptor properties for Graphics Interchange Format (GIF) metadata.
-[VT_UI1 | VT_VECTOR] Indicates the signature property.
[VT_UI2] Indicates the width in pixels.
[VT_UI2] Indicates the height in pixels.
[VT_BOOL] Indicates the global color table flag. TRUE if a global color table is present; otherwise,
[VT_UI1] Indicates the color resolution in bits per pixel.
[VT_BOOL] Indicates the sorted color table flag. TRUE if the table is sorted; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
[VT_UI1] Indicates the index within the color table to use for the background (pixels not defined in the image).
[VT_UI1] Indicates the factor used to compute an approximation of the aspect ratio.
Specifies the JPEG chrominance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a chrominance table.
Specifies the JPEG comment properties.
-Indicates the metadata property is comment text.
Specifies the JPEG luminance table property.
-[VT_UI2|VT_VECTOR] Indicates the metadata property is a luminance table.
Specifies the JPEG YCrCB subsampling options.
-The native JPEG encoder uses
The default subsampling option.
Subsampling option that uses both horizontal and vertical decimation.
Subsampling option that uses horizontal decimation .
Subsampling option that uses no decimation.
Specifies named white balances for raw images.
-The default white balance.
A daylight white balance.
A cloudy white balance.
A shade white balance.
A tungsten white balance.
A fluorescent white balance.
Daylight white balance.
A flash white balance.
A custom white balance. This is typically used when using a picture (grey-card) as white balance.
An automatic balance.
An "as shot" white balance.
Specifies the Portable Network Graphics (PNG) background (bKGD) chunk metadata properties.
-Indicates the background color. There are three possible types, depending on the image's pixel format.
Specifies the index of the background color in an image with an indexed pixel format.
Specifies the background color in a grayscale image.
Specifies the background color in an RGB image as three USHORT values: {0xRRRR, 0xGGGG, 0xBBBB}.
Specifies the Portable Network Graphics (PNG) cHRM chunk metadata properties for CIE XYZ chromaticity.
-[VT_UI4] Indicates the whitepoint x value ratio.
[VT_UI4] Indicates the whitepoint y value ratio.
[VT_UI4] Indicates the red x value ratio.
[VT_UI4] Indicates the red y value ratio.
[VT_UI4] Indicates the green x value ratio.
[VT_UI4] Indicates the green y value ratio.
[VT_UI4] Indicates the blue x value ratio.
[VT_UI4] Indicates the blue y value ratio.
Specifies the Portable Network Graphics (PNG) filters available for compression optimization.
-Indicates an unspecified PNG filter. This enables WIC to algorithmically choose the best filtering option for the image.
Indicates no PNG filter.
Indicates a PNG sub filter.
Indicates a PNG up filter.
Indicates a PNG average filter.
Indicates a PNG paeth filter.
Indicates a PNG adaptive filter. This enables WIC to choose the best filtering mode on a per-scanline basis.
Specifies the Portable Network Graphics (PNG) gAMA chunk metadata properties.
-[VT_UI4] Indicates the gamma value.
Specifies the Portable Network Graphics (PNG) hIST chunk metadata properties.
-[VT_VECTOR | VT_UI2] Indicates the approximate usage frequency of each color in the color palette.
Specifies the Portable Network Graphics (PNG) iCCP chunk metadata properties.
-[VT_LPSTR] Indicates the International Color Consortium (ICC) profile name.
[VT_VECTOR | VT_UI1] Indicates the embedded ICC profile.
Specifies the Portable Network Graphics (PNG) iTXT chunk metadata properties.
-[VT_LPSTR] Indicates the keywords in the iTXT metadata chunk.
[VT_UI1] Indicates whether the text in the iTXT chunk is compressed. 1 if the text is compressed; otherwise, 0.
[VT_LPSTR] Indicates the human language used by the translated keyword and the text.
[VT_LPWSTR] Indicates a translation of the keyword into the language indicated by the language tag.
[VT_LPWSTR] Indicates additional text in the iTXT metadata chunk.
Specifies the Portable Network Graphics (PNG) sRGB chunk metadata properties.
-[VT_UI1] Indicates the rendering intent for an sRGB color space image. The rendering intents have the following meaning.
| Value | Meaning |
|---|---|
| 0 | Perceptual |
| 1 | Relative colorimetric |
| 2 | Saturation |
| 3 | Absolute colorimetric |
?
Specifies the Portable Network Graphics (PNG) tIME chunk metadata properties.
-[VT_UI2] Indicates the year of the last modification.
[VT_UI1] Indicates the month of the last modification.
[VT_UI1] Indicates day of the last modification.
[VT_UI1] Indicates the hour of the last modification.
[VT_UI1] Indicates the minute of the last modification.
[VT_UI1] Indicates the second of the last modification.
Specifies when the progress notification callback should be called.
-The callback should be called when codec operations begin.
The callback should be called when codec operations end.
The callback should be called frequently to report status.
The callback should be called on all available progress notifications.
Specifies the progress operations to receive notifications for.
-Receive copy pixel operation.
Receive write pixel operation.
Receive all progress operations available.
Specifies the capability support of a raw image.
-The capability is not supported.
The capability supports only get operations.
The capability supports get and set operations.
Specifies the parameter set used by a raw codec.
-An as shot parameter set.
A user adjusted parameter set.
A codec adjusted parameter set.
Specifies the render intent of the next CopyPixels call.
-Specifies the rotation capabilities of the codec.
-Rotation is not supported.
Set operations for rotation is not supported.
90 degree rotations are supported.
All rotation angles are supported.
Specifies the access level of a Windows Graphics Device Interface (GDI) section.
-Indicates a read only access level.
Indicates a read/write access level.
Specifies the Tagged Image File Format (TIFF) compression options.
-Indicates a suitable compression algorithm based on the image and pixel format.
Indicates no compression.
Indicates a CCITT3 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a CCITT4 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a LZW compression algorithm.
Indicates a RLE compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a ZIP compression algorithm.
Indicates an LZWH differencing algorithm.
Defines methods that add the concept of writeability and static in-memory representations of bitmaps to
Because of to the internal memory representation implied by the
Exposes methods that refers to a source from which pixels are retrieved, but cannot be written back to.
-This interface provides a common way of accessing and linking together bitmaps, decoders, format converters, and scalers. Components that implement this interface can be connected together in a graph to pull imaging data through.
This interface defines only the notion of readability or being able to produce pixels. Modifying or writing to a bitmap is considered to be a specialization specific to bitmaps which have storage and is defined in the descendant interface
Retrieves the pixel width and height of the bitmap.
-A reference that receives the pixel width of the bitmap.
A reference that receives the pixel height of the bitmap
If this method succeeds, it returns
Retrieves the pixel format of the bitmap source..
-Receives the pixel format
If this method succeeds, it returns
The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the sampling rate between pixels and physical world measurements.
-A reference that receives the x-axis dpi resolution.
A reference that receives the y-axis dpi resolution.
If this method succeeds, it returns
Some formats, such as GIF and ICO, do not have full DPI support. For GIF, this method calculates the DPI values from the aspect ratio, using a base DPI of (96.0, 96.0). The ICO format does not support DPI at all, and the method always returns (96.0,96.0) for ICO images.
Additionally, WIC itself does not transform images based on the DPI values in an image. It is up to the caller to transform an image based on the resolution returned.
-Retrieves the color table for indexed pixel formats.
-An
Returns one of the following values.
| Return code | Description |
|---|---|
| | The palette was unavailable. |
| | The palette was successfully copied. |
?
If the
Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
The size of the buffer.
A reference to the buffer.
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-The rectangle to copy. A
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Instructs the object to produce pixels.
-If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
-Retrieves the pixel format of the bitmap source..
-The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
-Retrieves the pixel width and height of the bitmap.
-Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-The palette to use for conversion.
If this method succeeds, it returns
Changes the physical resolution of the image.
-The horizontal resolution.
The vertical resolution.
If this method succeeds, it returns
This method has no effect on the actual pixels or samples stored in the bitmap. Instead the interpretation of the sampling rate is modified. This means that a 96 DPI image which is 96 pixels wide is one inch. If the physical resolution is modified to 48 DPI, then the bitmap is considered to be 2 inches wide but has the same number of pixels. If the resolution is less than REAL_EPSILON (1.192092896e-07F) the error code
Provides access to a rectangular area of the bitmap.
-The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access to a rectangular area of the bitmap.
-The rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
-Exposes methods that produce a clipped version of the input bitmap for a specified rectangular region of interest.
-Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Initializes the bitmap clipper with the provided parameters.
-he input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Exposes methods that provide information about a particular codec.
-Exposes methods that provide component information.
-Retrieves the component's
If this method succeeds, it returns
Retrieves the component's class identifier (CLSID)
-A reference that receives the component's CLSID.
If this method succeeds, it returns
Retrieves the signing status of the component.
-A reference that receives the
If this method succeeds, it returns
Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the name of component's author.
-The size of the wzAuthor buffer.
A reference that receives the name of the component's author. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's authors name. The author name is optional; if an author name is not specified by the component, the length returned is 0.
If this method succeeds, it returns
If cchAuthor is 0 and wzAuthor is
Retrieves the vendor
A reference that receives the component's vendor
If this method succeeds, it returns
Retrieves the component's version.
-The size of the wzVersion buffer.
A reference that receives a culture invariant string of the component's version.
A reference that receives the actual length of the component's version. The version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's specification version.
-The size of the wzSpecVersion buffer.
When this method returns, contain a culture invarient string of the component's specification version. The version form is NN.NN.NN.NN.
A reference that receives the actual length of the component's specification version. The specification version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return "1.0.0.0", except for pixel formats, which do not have a spec version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's friendly name, which is a human-readable display name for the component.
-The size of the wzFriendlyName buffer.
A reference that receives the friendly name of the component. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's friendly name.
If this method succeeds, it returns
If cchFriendlyName is 0 and wzFriendlyName is
Retrieves the component's
Retrieves the component's class identifier (CLSID)
-Retrieves the signing status of the component.
-Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
-Retrieves the vendor
Retrieves the container
Receives the container
If this method succeeds, it returns
Retrieves the pixel formats the codec supports.
-The size of the pguidPixelFormats array. Use 0 on first call to determine the needed array size.
Receives the supported pixel formats. Use
The array size needed to retrieve all supported pixel formats.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the array size needed to retrieve all the supported pixel formats by calling it with cFormats set to 0 and pguidPixelFormats set to
Retrieves the color manangement version number the codec supports.
-The size of the version buffer. Use 0 on first call to determine needed buffer size.
Receives the color management version number. Use
The actual buffer size needed to retrieve the full color management version number.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchColorManagementVersion set to 0 and wzColorManagementVersion set to
Retrieves the name of the device manufacture associated with the codec.
-The size of the device manufacture's name. Use 0 on first call to determine needed buffer size.
Receives the device manufacture's name. Use
The actual buffer size needed to retrieve the device manufacture's name.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceManufacturer set to 0 and wzDeviceManufacturer set to
Retrieves a comma delimited list of device models associated with the codec.
-The size of the device models buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of device model names associated with the codec. Use
The actual buffer size needed to retrieve all of the device model names.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceModels set to 0 and wzDeviceModels set to
Retrieves a comma delimited sequence of mime types associated with the codec.
-The size of the mime types buffer. Use 0 on first call to determine needed buffer size.
Receives the mime types associated with the codec. Use
The actual buffer size needed to retrieve all mime types associated with the codec.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchMimeTypes set to 0 and wzMimeTypes set to
Retrieves a comma delimited list of the file name extensions associated with the codec.
-The size of the file name extension buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of file name extensions associated with the codec. Use
The actual buffer size needed to retrieve all file name extensions associated with the codec.
If this method succeeds, it returns
The default extension for an image encoder is the first item in the list of returned extensions.
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchFileExtensions set to 0 and wzFileExtensions set to
Retrieves a value indicating whether the codec supports animation.
-Receives TRUE if the codec supports images with timing information; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports chromakeys.
-Receives TRUE if the codec supports chromakeys; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports lossless formats.
-Receives TRUE if the codec supports lossless formats; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports multi frame images.
-Receives TRUE if the codec supports multi frame images; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the given mime type matches the mime type of the codec.
-The mime type to compare.
Receives TRUE if the mime types match; otherwise,
Retrieves the container
Retrieves a value indicating whether the codec supports animation.
-Retrieves a value indicating whether the codec supports chromakeys.
-Retrieves a value indicating whether the codec supports lossless formats.
-Retrieves a value indicating whether the codec supports multi frame images.
-Registers a progress notification callback function.
-A function reference to the application defined progress notification callback function. See ProgressNotificationCallback for the callback signature.
A reference to component data for the callback method.
The
If this method succeeds, it returns
Applications can only register a single callback. Subsequent registration calls will replace the previously registered callback. To unregister a callback, pass in
Progress is reported in an increasing order between 0.0 and 1.0. If dwProgressFlags includes
Exposes methods that represent a decoder.
The interface provides access to the decoder's properties such as global thumbnails (if supported), frames, and palette.
-There are a number of concrete implemenations of this interface representing each of the standard decoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), icon (ICO), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native decoder.
| CLSID Name | CLSID |
|---|---|
| 0x6b462062, 0x7cbf, 0x400d, 0x9f, 0xdb, 0x81, 0x3d, 0xd1, 0xf, 0x27, 0x78 | |
| 0x389ea17b, 0x5078, 0x4cde, 0xb6, 0xef, 0x25, 0xc1, 0x51, 0x75, 0xc7, 0x51 | |
| 0xc61bfcdf, 0x2e0f, 0x4aad, 0xa8, 0xd7, 0xe0, 0x6b, 0xaf, 0xeb, 0xcd, 0xfe | |
| 0x9456a480, 0xe88b, 0x43ea, 0x9e, 0x73, 0xb, 0x2d, 0x9b, 0x71, 0xb1, 0xca | |
| 0x381dda3c, 0x9ce9, 0x4834, 0xa2, 0x3e, 0x1f, 0x98, 0xf8, 0xfc, 0x52, 0xbe | |
| 0xb54e85d9, 0xfe23, 0x499f, 0x8b, 0x88, 0x6a, 0xce, 0xa7, 0x13, 0x75, 0x2b | |
| 0xa26cec36, 0x234c, 0x4950, 0xae, 0x16, 0xe3, 0x4a, 0xac, 0xe7, 0x1d, 0x0d |
?
This interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
Codecs written as TIFF container formats that are not register will decode as a TIFF image. Client applications should check for a zero frame count to determine if the codec is valid.
-Retrieves the capabilities of the decoder based on the specified stream.
-The stream to retrieve the decoder capabilities from.
The
Custom decoder implementations should save the current position of the specified
Initializes the decoder with the provided stream.
-The stream to use for initialization.
The stream contains the encoded pixels which are decoded each time the CopyPixels method on the
The
If this method succeeds, it returns
Retrieves the image's container format.
-A reference that receives the image's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Copies the decoder's
If this method succeeds, it returns
CopyPalette returns a global palette (a palette that applies to all the frames in the image) if there is one; otherwise, it returns
Retrieves the metadata query reader from the decoder.
-Receives a reference to the decoder's
If this method succeeds, it returns
Retrieves a preview image, if supported.
-Receives a reference to the preview bitmap if supported.
If this method succeeds, it returns
Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a bitmap thumbnail of the image, if one exists
-Receives a reference to the
If this method succeeds, it returns
None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-A reference that receives the total number of frames in the image.
If this method succeeds, it returns
Retrieves the specified frame of the image.
-The particular frame to retrieve.
A reference that receives a reference to the
Retrieves the image's container format.
-Retrieves an
Retrieves the metadata query reader from the decoder.
-Retrieves a preview image, if supported.
-Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
-Retrieves a bitmap thumbnail of the image, if one exists
-None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
-Retrieves the total number of frames in the image.
-Exposes methods that provide information about a decoder.
-Retrieves the file pattern signatures supported by the decoder.
-The array size of the pPatterns array.
Receives a list of
Receives the number of patterns the decoder supports.
Receives the actual buffer size needed to retrieve all pattern signatures supported by the decoder.
If this method succeeds, it returns
To retrieve all pattern signatures, this method should first be called with pPatterns set to
Retrieves a value that indicates whether the codec recognizes the pattern within a specified stream.
-The stream to pattern match within.
A reference that receives TRUE if the patterns match; otherwise,
Creates a new
If this method succeeds, it returns
Defines methods for setting an encoder's properties such as thumbnails, frames, and palettes.
-There are a number of concrete implemenations of this interface representing each of the standard encoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native encoder.
| CLSID Name | CLSID |
|---|---|
| 0x69be8bb4, 0xd66d, 0x47c8, 0x86, 0x5a, 0xed, 0x15, 0x89, 0x43, 0x37, 0x82 | |
| 0x27949969, 0x876a, 0x41d7, 0x94, 0x47, 0x56, 0x8f, 0x6a, 0x35, 0xa4, 0xdc | |
| 0x1a34f5c1, 0x4a5a, 0x46dc, 0xb6, 0x44, 0x1f, 0x45, 0x67, 0xe7, 0xa6, 0x76 | |
| 0x114f5598, 0xb22, 0x40a0, 0x86, 0xa1, 0xc8, 0x3e, 0xa4, 0x95, 0xad, 0xbd | |
| 0x0131be10, 0x2001, 0x4c5f, 0xa9, 0xb0, 0xcc, 0x88, 0xfa, 0xb6, 0x4c, 0xe8 | |
| 0xac4ce3cb, 0xe1c1, 0x44cd, 0x82, 0x15, 0x5a, 0x16, 0x65, 0x50, 0x9e, 0xc2 |
?
Additionally this interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
-Initializes the encoder with an
If this method succeeds, it returns
Retrieves the encoder's container format.
-A reference that receives the encoder's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the global palette for the image.
-The
Returns
Returns
Sets the global thumbnail for the image.
-The
Returns
Returns
Sets the global preview for the image.
-The
Returns
Returns
Creates a new
If this method succeeds, it returns
The parameter ppIEncoderOptions can be used to receive an
Note??Do not pass in a reference to an initialized
Otherwise, you can pass
See Encoding Overview for an example of how to set encoder options.
-Commits all changes for the image and closes the stream.
-If this method succeeds, it returns
To finalize an image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Retrieves a metadata query writer for the encoder.
-When this method returns, contains a reference to the encoder's metadata query writer.
If this method succeeds, it returns
Retrieves the encoder's container format.
-Retrieves an
Sets the global palette for the image.
-Sets the global thumbnail for the image.
-Sets the global preview for the image.
-Retrieves a metadata query writer for the encoder.
-Exposes methods that provide information about an encoder.
-Creates a new
If this method succeeds, it returns
Exposes methods that produce a flipped (horizontal or vertical) and/or rotated (by 90 degree increments) bitmap source. Rotations are done before the flip.
-IWICBitmapFipRotator requests data on a per-pixel basis, while WIC codecs provide data on a per-scanline basis. This causes the fliprotator object to exhibit n2 behavior if there is no buffering. This occures because each pixel in the transformed image requires an entire scanline to be decoded in the file. It is recommended that you buffer the image using
Initializes the bitmap flip rotator with the provided parameters.
-The input bitmap source.
The
If this method succeeds, it returns
Defines methods for decoding individual image frames of an encoded file.
-Retrieves a metadata query reader for the frame.
-When this method returns, contains a reference to the frame's metadata query reader.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a small preview of the frame, if supported by the codec.
-A reference that receives a reference to the
If this method succeeds, it returns
Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Retrieves a metadata query reader for the frame.
-Retrieves a small preview of the frame, if supported by the codec.
-Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
-Represents an encoder's individual image frames.
-Initializes the frame encoder using the given properties.
-The set of properties to use for
If this method succeeds, it returns
Sets the output image dimensions for the frame.
-The width of the output image.
The height of the output image.
If this method succeeds, it returns
Sets the physical resolution of the output image.
-The horizontal resolution value.
The vertical resolution value.
If this method succeeds, it returns
Requests that the encoder use the specified pixel format.
-If the method succeeds, contains the specified pixel format
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The |
?
Sets a given number
If this method succeeds, it returns
Sets a given number
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-The bitmap source to use as the thumbnail.
Returns
Returns
SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
The size of the pixel buffer.
A reference to the pixel buffer.
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The value of lineCount is larger than the number of scan lines in the image. |
?
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If this method succeeds, it returns
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Commits the frame to the image.
-If this method succeeds, it returns
To finalize the image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
-Gets the metadata query writer for the encoder frame.
-When this method returns, contains a reference to metadata query writer for the encoder frame.
If this method succeeds, it returns
Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes the frame scanlines.
-The number of lines to encode.
The stride of the image pixels.
A reference to the pixel buffer.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
-Encodes a bitmap source.
-The bitmap source to encode.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Encodes a bitmap source.
-The bitmap source to encode.
The size rectangle of the bitmap source.
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
-Sets the
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
-Sets the frame thumbnail if supported by the codec.
-SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
-Gets the metadata query writer for the encoder frame.
-Exposes methods that support the Lock method.
-The bitmap lock is simply an abstraction for a rectangular memory window into the bitmap. For the simplest case, a system memory bitmap, this is simply a reference to the top left corner of the rectangle and a stride value.
To release the exclusive lock set by Lock method and the associated
Retrieves the width and height, in pixels, of the locked rectangle.
-A reference that receives the width of the locked rectangle.
A reference that receives the height of the locked rectangle.
If this method succeeds, it returns
Provides access to the stride value for the memory.
-If this method succeeds, it returns
Note the stride value is specific to the
Gets the reference to the top left pixel in the locked rectangle.
-A reference that receives the size of the buffer.
A reference that receives a reference to the top left pixel in the locked rectangle.
The reference provided by this method should not be used outside of the lifetime of the lock itself.
GetDataPointer is not available in multi-threaded apartment applications.
-Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-A reference that receives the pixel format
If this method succeeds, it returns
Provides access to the stride value for the memory.
- Note the stride value is specific to the
Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
-Represents a resized version of the input bitmap using a resampling or filtering algorithm.
-Images can be scaled to larger sizes; however, even with sophisticated scaling algorithms, there is only so much information in the image and artifacts tend to worsen the more you scale up.
The scaler will reapply the resampling algorithm every time CopyPixels is called. If the scaled image is to be animated, the scaled image should be created once and cached in a new bitmap, after which the
The scaler is optimized to use the minimum amount of memory required to scale the image correctly. The scaler may be used to produce parts of the image incrementally (banding) by calling CopyPixels with different rectangles representing the output bands of the image. Resampling typically requires overlapping rectangles from the source image and thus may need to request the same pixels from the source bitmap multiple times. Requesting scanlines out-of-order from some image decoders can have a significant performance penalty. Because of this reason, the scaler is optimized to handle consecutive horizontal bands of scanlines (rectangle width equal to the bitmap width). In this case the accumulator from the previous vertically adjacent rectangle is re-used to avoid duplicate scanline requests from the source. This implies that banded output from the scaler may have better performance if the bands are requested sequentially. Of course if the scaler is simply used to produce a single rectangle output, this concern is eliminated because the scaler will internally request scanlines in the correct order.
-Initializes the bitmap scaler with the provided parameters.
-The input bitmap source.
The destination width.
The desination height.
The
If this method succeeds, it returns
Copies pixel data using the supplied input parameters.
-The rectangle of pixels to copy.
The width to scale the source bitmap. This parameter must equal the value obtainable through
The height to scale the source bitmap. This parameter must equal the value obtainable through
The
This
The desired rotation or flip to perform prior to the pixel copy.
The transform must be an operation supported by an DoesSupportTransform call.
If a dstTransform is specified, nStride is the transformed stride and is based on the pguidDstFormat pixel format, not the original source's pixel format.
The stride of the destination buffer.
The size of the destination buffer.
The output buffer.
If this method succeeds, it returns
For codec developer implementation details for this method, see Implementing
When multiple transform operations are requested, the result is dependent on the order in which the operations are performed. To ensure predictability and consistency across CODECs, it's important that all CODECs perform these operations in the same order. The recommended order of these operations is:
Pixel format conversion can be performed at any time, since it has no effect on the other transforms.
The first parameter, prc is used to specify the region of interest for clipping the image. By convention, scaling is performed before clipping so, if the image is to be scaled as well as clipped, the region of interest should be determined after the image has been scaled.
If a dstTransform is specified, the stride is the transformed stride, and is based on the pixelFormat specified in the CopyPixels call, not the original frame's pixel format.
-Returns the closest dimensions the implementation can natively scale to given the desired dimensions.
-The desired width. A reference that receives the closest supported width.
The desired height.A reference that receives the closest supported height.
If this method succeeds, it returns
Retrieves the closest pixel format to which the implementation of
If this method succeeds, it returns
Determines whether a specific transform option is supported natively by the implementation of the
If this method succeeds, it returns
Exposes methods for color management.
-A Color Context is an abstraction for a color profile. The profile can be loaded from a file (ie. "sRGB Color Space Profile.icm") or from a memory buffer obtained by reading. The color profile directory can be obtained by calling the GetColorDirectory API (See http://msdn.microsoft.com/library/en-us/icm/icm_58xl.asp).
-Initializes the color context from the given file.
-If this method succeeds, it returns
Initializes the color context from a memory block.
-The buffer used to initialize the
The size of the pbBuffer buffer.
If this method succeeds, it returns
Initializes the color context using an Exchangeable Image File (EXIF) color space.
-The value of the EXIF color space.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
?
If this method succeeds, it returns
Retrieves the color context type.
-A reference that receives the
If this method succeeds, it returns
Retrieves the color context profile.
-The size of the pbBuffer buffer.
A reference that receives the color context profile.
A reference that receives the actual buffer size needed to retrieve the entire color context profile.
If this method succeeds, it returns
Retrieves the Exchangeable Image File (EXIF) color space color context.
-A reference that receives the EXIF color space color context.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
| Unused. |
?
If this method succeeds, it returns
Retrieves the color context type.
-Retrieves the Exchangeable Image File (EXIF) color space color context.
-Exposes methods that transforms an
A
Initializes an
If this method succeeds, it returns
Exposes methods that provide access to the capabilites of a raw codec format.
-Retrieves information about which capabilities are supported for a raw image.
-A reference that receives
If this method succeeds, it returns
It is recommended that a codec report that a capability is supported even if the results at the outer range limits are not of perfect quality.
-Sets the desired
If this method succeeds, it returns
Gets the current set of parameters.
-A reference that receives a reference to the current set of parameters.
If this method succeeds, it returns
Sets the exposure compensation stop value.
-The exposure compensation value. The value range for exposure compensation is -5.0 through +5.0, which equates to 10 full stops.
If this method succeeds, it returns
It is recommended that a codec report that this method is supported even if the results at the outer range limits are not of perfect quality.
-Gets the exposure compensation stop value of the raw image.
-A reference that receives the exposure compensation stop value. The default is the "as-shot" setting.
If this method succeeds, it returns
Sets the white point RGB values.
-The red white point value.
The green white point value.
The blue white point value.
If this method succeeds, it returns
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the white point RGB values.
-A reference that receives the red white point value.
A reference that receives the green white point value.
A reference that receives the blue white point value.
If this method succeeds, it returns
Sets the named white point of the raw file.
-A bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in the API.
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the named white point of the raw image.
-A reference that receives the bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Sets the white point Kelvin value.
-The white point Kelvin value. Acceptable Kelvin values are 1,500 through 30,000.
If this method succeeds, it returns
Codec implementers should faithfully adjust the color temperature within the range supported natively by the raw image. For values outside the native support range, the codec implementer should provide a best effort representation of the image at that color temperature.
Codec implementers should return
Codec implementers must ensure proper interoperability with other white point setting methods such as SetWhitePointRGB. For example, if the caller sets the white point via SetNamedWhitePoint then the codec implementer may want to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wants to deny a given action because of previous calls,
Gets the white point Kelvin temperature of the raw image.
-A reference that receives the white point Kelvin temperature of the raw image. The default is the "as-shot" setting value.
If this method succeeds, it returns
Gets the information about the current Kelvin range of the raw image.
-A reference that receives the minimum Kelvin temperature.
A reference that receives the maximum Kelvin temperature.
A reference that receives the Kelvin step value.
If this method succeeds, it returns
Sets the contrast value of the raw image.
-The contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the contrast value of the raw image.
-A reference that receives the contrast value of the raw image. The default value is the "as-shot" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
Sets the desired gamma value.
-The desired gamma value.
If this method succeeds, it returns
Gets the current gamma setting of the raw image.
-A reference that receives the current gamma setting.
If this method succeeds, it returns
Sets the sharpness value of the raw image.
-The sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the sharpness value of the raw image.
-A reference that receives the sharpness value of the raw image. The default value is the "as-shot" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
Sets the saturation value of the raw image.
-The saturation value of the raw image. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the saturation value of the raw image.
-A reference that receives the saturation value of the raw image. The default value is the "as-shot" setting. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
Sets the tint value of the raw image.
-The tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
The codec implementer must determine what the outer range values represent and must determine how to map the values to their image processing routines.
-Gets the tint value of the raw image.
-A reference that receives the tint value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
Sets the noise reduction value of the raw image.
-The noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents highest noise reduction amount that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
-Gets the noise reduction value of the raw image.
-A reference that receives the noise reduction value of the raw image. The default value is the "as-shot" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents full highest noise reduction amount that can be applied.
If this method succeeds, it returns
Sets the destination color context.
-The destination color context.
If this method succeeds, it returns
Sets the tone curve for the raw image.
-The size of the pToneCurve structure.
The desired tone curve.
If this method succeeds, it returns
Gets the tone curve of the raw image.
-The size of the pToneCurve buffer.
A reference that receives the
A reference that receives the size needed to obtain the tone curve structure.
If this method succeeds, it returns
Sets the desired rotation angle.
-The desired rotation angle.
If this method succeeds, it returns
Gets the current rotation angle.
-A reference that receives the current rotation angle.
If this method succeeds, it returns
Sets the current
If this method succeeds, it returns
Gets the current
If this method succeeds, it returns
Sets the notification callback method.
-Pointer to the notification callback method.
If this method succeeds, it returns
Gets the current set of parameters.
-Gets or sets the exposure compensation stop value of the raw image.
-Gets or sets the named white point of the raw image.
-If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Gets or sets the white point Kelvin temperature of the raw image.
-Gets or sets the contrast value of the raw image.
-Gets or sets the current gamma setting of the raw image.
-Gets or sets the sharpness value of the raw image.
-Gets or sets the saturation value of the raw image.
-Gets or sets the tint value of the raw image.
-Gets or sets the noise reduction value of the raw image.
-Sets the destination color context.
-Gets or sets the current rotation angle.
-Gets or sets the current
Sets the notification callback method.
-Flags used to by
An application-defined callback method used for raw image parameter change notifications.
-A set of
If this method succeeds, it returns
Exposes methods that provide enumeration services for individual metadata items.
-Skips to given number of objects.
-The number of objects to skip.
If this method succeeds, it returns
Resets the current position to the beginning of the enumeration.
-If this method succeeds, it returns
Creates a copy of the current
If this method succeeds, it returns
Exposes methods used for in-place metadata editing. A fast metadata encoder enables you to add and remove metadata to an image without having to fully re-encode the image.
- A decoder must be created using the
Not all metadata formats support fast metadata encoding. The native metadata handlers that support metadata are IFD, Exif, XMP, and GPS.
If a fast metadata encoder fails, the image will need to be fully re-encoded to add the metadata.
-Finalizes metadata changes to the image stream.
-If this method succeeds, it returns
If the commit fails and returns
If the commit fails for any reason, you will need to re-encode the image to ensure the new metadata is added to the image.
-Retrieves a metadata query writer for fast metadata encoding.
-When this method returns, contains a reference to the fast metadata encoder's metadata query writer.
If this method succeeds, it returns
Retrieves a metadata query writer for fast metadata encoding.
- Represents an
Initializes the format converter.
-The input bitmap to convert
The destination pixel format
The
The palette to use for conversion.
The alpha threshold to use for conversion.
The palette translation type to use for conversion.
If this method succeeds, it returns
If you do not have a predefined palette, you must first create one. Use InitializeFromBitmap to create the palette object, then pass it in along with your other parameters.
dither, pIPalette, alphaThresholdPercent, and paletteTranslate are used to mitigate color loss when converting to a reduced bit-depth format. For conversions that do not need these settings, the following parameters values should be used: dither set to
The basic algorithm involved when using an ordered dither requires a fixed palette, found in the
If colors in pIPalette do not closely match those in paletteTranslate, the mapping may produce undesireable results.
When converting a bitmap which has an alpha channel, such as a Portable Network Graphics (PNG), to 8bpp, the alpha channel is normally ignored. Any pixels which were transparent in the original bitmap show up as black in the final output because both transparent and black have pixel values of zero in the respective formats.
Some 8bpp content can contains an alpha color; for instance, the Graphics Interchange Format (GIF) format allows for a single palette entry to be used as a transparent color. For this type of content, alphaThresholdPercent specifies what percentage of transparency should map to the transparent color. Because the alpha value is directly proportional to the opacity (not transparency) of a pixel, the alphaThresholdPercent indicates what level of opacity is mapped to the fully transparent color. For instance, 9.8% implies that any pixel with an alpha value of less than 25 will be mapped to the transparent color. A value of 100% maps all pixels which are not fully opaque to the transparent color. Note that the palette should provide a transparent color. If it does not, the 'transparent' color will be the one closest to zero - often black.
-Determines if the source pixel format can be converted to the destination pixel format.
-The source pixel format.
The destionation pixel format.
A reference that receives a value indicating whether the source pixel format can be converted to the destination pixel format.
Exposes methods that provide information about a pixel format converter.
-Retrieves a list of GUIDs that signify which pixel formats the converter supports.
-The size of the pPixelFormatGUIDs array.
Pointer to a
The actual array size needed to retrieve all pixel formats supported by the converter.
If this method succeeds, it returns
The format converter does not necessarily guarantee symmetricality with respect to conversion; that is, a converter may be able to convert FROM a particular format without actually being able to convert TO a particular format. In order to test symmetricality, use CanConvert.
To determine the number of pixel formats a coverter can handle, set cFormats to 0 and pPixelFormatGUIDs to
Creates a new
If this method succeeds, it returns
This section contains information about the Windows Imaging Component (WIC) interfaces.
-
Exposes methods used to create components for the Windows Imaging Component (WIC) such as decoders, encoders and pixel format converters.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
When a decoder is created using this method, the file handle must remain alive during the lifetime of the decoder.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Other values may be available for both guidContainerFormat and pguidVendor depending on the installed WIC-enabled encoders. The values listed are those that are natively supported by the operating system.
-Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Component types must be enumerated seperately. Combinations of component types and
Creates a new instance of the fast metadata encoder based on the given
If this method succeeds, it returns
The native image formats provided by Windows Imaging Component (WIC) do not support metadata at the decoder level. WIC codecs only support metadata on image frames. To create a fast metadata encoder from an image frame, see the image factory's CreateFastMetadataEncoderFromFrameDecode method.
-Creates a new instance of the fast metadata encoder based on the given image frame.
-The
When this method returns, contains a reference to a new fast metadata encoder.
If this method succeeds, it returns
Creates a new instance of a query writer.
-The
The
When this method returns, contains a reference to a new
If this method succeeds, it returns
Creates a new instance of a query writer based on the given query reader. The query writer will be pre-populated with metadata from the query reader.
-The
The
When this method returns, contains a reference to a new metadata writer.
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Exposes methods used to create components for the Windows Imaging Component (WIC) such as decoders, encoders and pixel format converters.
-Exposes methods for retrieving metadata blocks and items from a decoder or its image frames using a metadata query expression.
-A metadata query reader uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Gets the metadata query readers container format.
-Pointer that receives the cointainer format
If this method succeeds, it returns
Retrieves the current path relative to the root metadata block.
-The length of the wzNamespace buffer.
Pointer that receives the current namespace location.
The actual buffer length that was needed to retrieve the current namespace location.
If this method succeeds, it returns
If the query reader is relative to the top of the metadata hierarchy it will return an empty string.
If the query reader is relative to a nested metadata block this method will return the path to the current query reader.
-Retrieves the metadata block or item identified by a metadata query expression.
-The query expression to the requested metadata block or item.
When this method returns, contains the metadata block or item requested.
If this method succeeds, it returns
GetMetadataByName uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If multiple blocks or items exist that are expressed by the same query expression, the first metadata block or item found will be returned.
-Gets an enumerator of all metadata items at the current relative location within the metadata hierachy.
-When this method returns, contais a reference to an enumerator that contains the metadata items.
If a metadata item is a nested metadata block it will be passed back as a VT_UNKNOWN; otherwise, the "name" of the property will be passed back as a VT_LPWSTR. The enumerator does not enumerate content within nested metadata blocks.
Gets the metadata query readers container format.
-Exposes methods for setting or removing metadata blocks and items to an encoder or its image frames using a metadata query expression.
-A metadata query writer uses metadata query expressions to set or remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
-Sets a metadata item to a specific location.
-The name of the metadata item.
The metadata to set.
If this method succeeds, it returns
SetMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the value set is a nested metadata block then use variant type VT_UNKNOWN and pvarValue pointing to the
Removes a metadata item from a specific location using a metadata query expression.
-The name of the metadata item to remove.
If this method succeeds, it returns
RemoveMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the metadata item is a metadata block, it is removed from the metadata hierarchy.
-Exposes methods for accessing and building a color table, primarily for indexed pixel formats.
-If the
InitializeFromBitmap's fAddTransparentColor parameter will add a transparent color to the end of the color collection if its size if less than 256, otherwise index 255 will be replaced with the transparent color. If a pre-defined palette type is used, it will change to BitmapPaletteTypeCustom since it no longer matches the predefined palette.
The palette interface is an auxiliary imaging interface in that it does not directly concern bitmaps and pixels; rather it provides indexed color translation for indexed bitmaps. For an indexed pixel format with M bits per pixels: (The number of colors in the palette) greater than 2^M.
Traditionally the basic operation of the palette is to provide a translation from a byte (or smaller) index into a 32bpp color value. This is often accomplished by a 256 entry table of color values.
-Initializes the palette to one of the pre-defined palettes specified by
If this method succeeds, it returns
Initializes a palette to the custom color entries provided.
-Pointer to the color array.
The number of colors in pColors.
If this method succeeds, it returns
If a transparent color is required, it should be provided as part of the custom entries.
The entry count is limited to 256.
-Initializes a palette using a computed optimized values based on the reference bitmap.
-Pointer to the source bitmap.
The number of colors to initialize the palette with.
A value to indicate whether to add a transparent color.
If this method succeeds, it returns
The resulting palette contains the specified number of colors which best represent the colors present in the bitmap. The algorithm operates on the opaque RGB color value of each pixel in the reference bitmap and hence ignores any alpha values. If a transparent color is required, set the fAddTransparentColor parameter to TRUE and one fewer optimized color will be computed, reducing the colorCount, and a fully transparent color entry will be added.
-Initialize the palette based on a given palette.
-Pointer to the source palette.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Pointer that receives the number of colors in the color table.
If this method succeeds, it returns
Fills out the supplied color array with the colors from the internal color table. The color array should be sized according to the return results from GetColorCount.
-If this method succeeds, it returns
Retrieves a value that describes whether the palette is black and white.
-Pointer that receives TRUE if the palette is black and white; otherwise,
If this method succeeds, it returns
Retrieves a value that describes whether a palette is grayscale.
-Pointer that receives TRUE if the palette is grayscale; otherwise
If this method succeeds, it returns
Retrieves a value that describes whether the palette contains an alpha transparent color.
-Pointer that receives TRUE if the palette contains a transparent color; otherwise,
If this method succeeds, it returns
Retrieves the
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
-Retrieves the number of colors in the color table.
-Retrieves a value that describes whether the palette is black and white.
-Retrieves a value that describes whether a palette is grayscale.
-Exposes methods that provide information about a pixel format.
-Gets the pixel format
Pointer that receives the pixel format
If this method succeeds, it returns
Gets the pixel format's
If this method succeeds, it returns
Gets the bits per pixel (BPP) of the pixel format.
-Pointer that receives the BPP of the pixel format.
If this method succeeds, it returns
Gets the number of channels the pixel format contains.
-Pointer that receives the channel count.
If this method succeeds, it returns
Gets the pixel format's channel mask.
-The index to the channel mask to retrieve.
The size of the pbMaskBuffer buffer.
Pointer to the mask buffer.
The actual buffer size needed to obtain the channel mask.
If this method succeeds, it returns
Gets the pixel format
Gets the pixel format's
Gets the bits per pixel (BPP) of the pixel format.
-Gets the number of channels the pixel format contains.
-Extends
Returns whether the format supports transparent pixels.
-Returns TRUE if the pixel format supports transparency; otherwise, false.
If this method succeeds, it returns
Returns the
If this method succeeds, it returns
Returns whether the format supports transparent pixels.
-Notify method is documented only for compliance; its use is not recommended and may be altered or unavailable in the future. Instead, and use RegisterProgressNotification. -
-If this method succeeds, it returns
Exposes methods for obtaining information about and controlling progressive decoding.
-Images can only be progressively decoded if they were progressively encoded. The native encoders supplied by Windows Imaging Component (WIC) do not
E_NOTIMPL is returned if the codec does not support progressive level decoding.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Indicates the number of levels supported by the CODEC.
If this method succeeds, it returns
Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets the last level set by the SetCurrentLevel call.
-If this method succeeds, it returns
Specifies the level to retrieve on the next call to CopyPixels.
-If this method succeeds, it returns
A call does not have to request every level supported. If a caller requests level 1, without having previously requested level 0, the bits returned by the next call to CopyPixels will include both levels.
-Gets the number of levels of progressive decoding supported by the CODEC.
-Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
-Gets or sets the last level set by the SetCurrentLevel call.
-Represents a Windows Imaging Component (WIC) stream for referencing imaging and metadata content.
-Decoders and metadata handlers are expected to create sub streams of whatever stream they hold when handing off control for embedded metadata to another metadata handler. If the stream is not restricted then use MAXLONGLONG as the max size and offset 0.
The
Initializes a stream from another stream. Access rights are inherited from the underlying stream.
-The initialize stream.
If this method succeeds, it returns
Initializes a stream from a particular file.
-The file used to initialize the stream.
The desired file access mode.
| Value | Meaning |
|---|---|
| Read access. |
| Write access. |
?
If this method succeeds, it returns
The
Initializes a stream to treat a block of memory as a stream. The stream cannot grow beyond the buffer size.
-Pointer to the buffer used to initialize the stream.
The size of buffer.
If this method succeeds, it returns
This method should be avoided whenever possible. The caller is responsible for ensuring the memory block is valid for the lifetime of the stream when using InitializeFromMemory. A workaround for this behavior is to create an
If you require a growable memory stream, use CreateStreamOnHGlobal.
-Initializes the stream as a substream of another stream.
-Pointer to the input stream.
The stream offset used to create the new stream.
The maximum size of the stream.
If this method succeeds, it returns
The stream functions with its own stream position, independent of the underlying stream but restricted to a region. All seek positions are relative to the sub region. It is allowed, though not recommended, to have multiple writable sub streams overlapping the same range.
-Contains members that identify a pattern within an image file which can be used to identify a particular format.
-The offset the pattern is located in the file.
The pattern length.
The actual pattern.
The pattern mask.
The end of the stream.
Defines raw codec capabilites.
-Size of the
The codec's major version.
The codec's minor version.
The
The
The
The
The
The
The
The
The
The
The
The
The
The
The
Represents a raw image tone curve.
-The number of tone curve points.
The array of tone curve points.
Represents a raw image tone curve point.
-The tone curve input.
The tone curve output.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the gradient stops from the collecton into memory.
-If the
If gradientStopsCount is less than the number of gradient stops in the collection, the remaining gradient stops are omitted. If gradientStopsCount is larger than the number of gradient stops in the collection, the extra gradient stops are set to
Represents an collection of
To create an
A gradient stop collection is a device-dependent resource: your application should create gradient stop collections after it initializes the render target with which the gradient stop collection will be used, and recreate the gradient stop collection whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Retrieves the number of gradient stops in the collection.
-The number of gradient stops in the collection.
Copies the gradient stops from the collection into an array of
Gradient stops are copied in order of position, starting with the gradient stop with the smallest position value and progressing to the gradient stop with the largest position value.
-Indicates the gamma space in which the gradient stops are interpolated.
-The gamma space in which the gradient stops are interpolated.
Indicates the behavior of the gradient outside the normalized gradient range.
-The behavior of the gradient outside the [0,1] normalized gradient range.
Retrieves the number of gradient stops in the collection.
-Indicates the gamma space in which the gradient stops are interpolated.
-Indicates the behavior of the gradient outside the normalized gradient range.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the gradient stops from the collecton into memory.
-When this method returns, contains a reference to a one-dimensional array of
The number of gradient stops to copy.
If the
If gradientStopsCount is less than the number of gradient stops in the collection, the remaining gradient stops are omitted. If gradientStopsCount is larger than the number of gradient stops in the collection, the extra gradient stops are set to
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the color space before interpolation occurs.
-This method returns the color space.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets thecolor space after interpolation has occured.
-This method returns the color space.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the precision of the gradient buffer.
-The buffer precision of the gradient buffer.
The buffer precision can be one of the following.
| Value | Device requirements |
|---|---|
| Available on all devices. | |
| The device must support 16-bit high color. | |
| The device must support 16-bit high color. | |
| The device must support 32-bit high color. |
?
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the color space before interpolation occurs.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets thecolor space after interpolation has occured.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the precision of the gradient buffer.
-The buffer precision can be one of the following.
| Value | Device requirements |
|---|---|
| Available on all devices. | |
| The device must support 16-bit high color. | |
| The device must support 16-bit high color. | |
| The device must support 32-bit high color. |
?
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a brush based on an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the image associated with the provided image brush.
-The image to be associated with the image brush.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets how the content inside the source rectangle in the image brush will be extended on the x-axis.
-The extend mode on the x-axis of the image.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the extend mode on the y-axis.
-The extend mode on the y-axis of the image.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the interpolation mode for the image brush.
-How the contents of the image will be interpolated to handle the brush transform.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the source rectangle in the image brush.
-The source rectangle that defines the portion of the image to tilet.
The top left corner of the sourceRectangle parameter maps to the brush space origin. That is, if the brush and world transforms are both identity, the portion of the image in the top left corner of the source rectangle will be rendered at (0,0) in the render target.
The source rectangle will be expanded differently depending on whether the input image is based on pixels (a bitmap or effect) or by a command list.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the image associated with the image brush.
-When this method returns, contains the address of a reference to the image associated with this brush.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode of the image brush on the x-axis.
-This method returns the x-extend mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode of the image brush on the y-axis of the image.
-This method returns the y-extend mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the interpolation mode of the image brush.
-This method returns the interpolation mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rectangle that will be used as the bounds of the image when drawn as an image brush.
-When this method returns, contains the address of the output source rectangle.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the image associated with the image brush.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode of the image brush on the x-axis.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extend mode of the image brush on the y-axis of the image.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the interpolation mode of the image brush.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the rectangle that will be used as the bounds of the image when drawn as an image brush.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Contains the content bounds, mask information, opacity settings, and other options for a layer resource.
-The content bounds of the layer. Content outside these bounds is not guaranteed to render.
The geometric mask specifies the area of the layer that is composited into the render target.
A value that specifies the antialiasing mode for the geometricMask.
A value that specifies the transform that is applied to the geometric mask when composing the layer.
An opacity value that is applied uniformly to all resources in the layer when compositing to the target.
A brush that is used to modify the opacity of the layer. The brush - is mapped to the layer, and the alpha channel of each mapped brush pixel is multiplied against the corresponding layer pixel.
Additional options for the layer creation.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents an abstract shape that may be composed of arcs, curves, and lines.
-This interface adds functionality to
Represents a complex shape that may be composed of arcs, curves, and lines.
-An
To create a path geometry, use the
Represents a geometry resource and defines a set of helper methods for manipulating and measuring geometric shapes. Interfaces that inherit from
There are several types of Direct2D geometry objects: a simple geometry (
Direct2D geometries enable you to describe two-dimensional figures and also offer many uses, such as defining hit-test regions, clip regions, and even animation paths.
Direct2D geometries are immutable and device-independent resources created by
Gets the bounds of the geometry after it has been widened by the specified stroke width and style and transformed by the specified matrix.
-The amount by which to widen the geometry by stroking its outline.
The style of the stroke that widens the geometry.
A transform to apply to the geometry after the geometry is transformed and after the geometry has been stroked.
When this method returns, contains the bounds of the widened geometry. You must allocate storage for this parameter.
Determines whether the geometry's stroke contains the specified point given the specified stroke thickness, style, and transform.
-The point to test for containment.
The thickness of the stroke to apply.
The style of stroke to apply.
The transform to apply to the stroked geometry.
When this method returns, contains a boolean value set to true if the geometry's stroke contains the specified point; otherwise, false. You must allocate storage for this parameter.
Indicates whether the area filled by the geometry would contain the specified point given the specified flattening tolerance.
-The point to test.
The transform to apply to the geometry prior to testing for containment, or
The numeric accuracy with which the precise geometric path and path intersection is calculated. Points missing the fill by less than the tolerance are still considered inside. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a
Describes the intersection between this geometry and the specified geometry. The comparison is performed by using the specified flattening tolerance.
-The geometry to test.
The transform to apply to inputGeometry, or
The maximum bounds on the distance between points in the polygonal approximation of the geometries. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to a value that describes how this geometry is related to inputGeometry. You must allocate storage for this parameter.
When interpreting the returned relation value, it is important to remember that the member
For more information about how to interpret other possible return values, see
Computes the outline of the geometry and writes the result to an
If this method succeeds, it returns
The Outline method allows the caller to produce a geometry with an equivalent fill to the input geometry, with the following additional properties:
Additionally, the Outline method can be useful in removing redundant portions of said geometries to simplify complex geometries. It can also be useful in combination with
Computes the area of the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The transform to apply to this geometry before computing its area, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this this method returns, contains a reference to the area of the transformed, flattened version of this geometry. You must allocate storage for this parameter.
Calculates the point and tangent vector at the specified distance along the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
-The distance along the geometry of the point and tangent to find. If this distance is less then 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry.
The transform to apply to the geometry before calculating the specified point and tangent, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to the tangent vector at the specified distance along the geometry. If the geometry is empty, this vector contains NaN as its x and y values. You must allocate storage for this parameter.
The location at the specified distance along the geometry. If the geometry is empty, this point contains NaN as its x and y values.
Widens the geometry by the specified stroke and writes the result to an
If this method succeeds, it returns
Retrieves the geometry sink that is used to populate the path geometry with figures and segments.
-When this method returns, geometrySink contains the address of a reference to the geometry sink that is used to populate the path geometry with figures and segments. This parameter is passed uninitialized.
Because path geometries are immutable and can only be populated once, it is an error to call Open on a path geometry more than once.
Note that the fill mode defaults to
Copies the contents of the path geometry to the specified
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-A reference that receives the number of segments in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of figures in the path geometry.
-A reference that receives the number of figures in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
-Retrieves the number of figures in the path geometry.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Computes the point that exists at a given distance along the path geometry along with the index of the segment the point is on and the directional vector at that point.
-The distance to walk along the path.
The index of the segment at which to begin walking. Note: This index is global to the entire path, not just a particular figure.
The transform to apply to the path prior to walking.
The flattening tolerance to use when walking along an arc or Bezier segment.
When this method returns, contains a description of the point that can be found at the given location.
The method returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | One of the inputs was in an invalid range. |
?
A length that is less than 0 or is not a number is treated as if it were 0.
If length is greater than the total length of the path, then the end point of the path is returned.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes the caps, miter limit, line join, and dash information for a stroke.
-This interface adds functionality to
Describes the caps, miter limit, line join, and dash information for a stroke.
-To create a stroke style, use the
A stroke style is a device-indenpendent resource; you can create it once then retain it for the life of your application. For more information about resources, see the Resources Overview.
-Retrieves the type of shape used at the beginning of a stroke.
-The type of shape used at the beginning of a stroke.
Retrieves the type of shape used at the end of a stroke.
-The type of shape used at the end of a stroke.
Gets a value that specifies how the ends of each dash are drawn.
-A value that specifies how the ends of each dash are drawn.
Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-A positive number greater than or equal to 1.0f that describes the limit on the ratio of the miter length to half the stroke's thickness.
Retrieves the type of joint used at the vertices of a shape's outline.
-A value that specifies the type of joint used at the vertices of a shape's outline.
Retrieves a value that specifies how far in the dash sequence the stroke will start.
-A value that specifies how far in the dash sequence the stroke will start.
Gets a value that describes the stroke's dash pattern.
-A value that describes the predefined dash pattern used, or
If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-The number of entries in the dashes array if the stroke is dashed; otherwise, 0.
Copies the dash pattern to the specified array.
-A reference to an array that will receive the dash pattern. The array must be able to contain at least as many elements as specified by dashesCount. You must allocate storage for this array.
The number of dashes to copy. If this value is less than the number of dashes in the stroke style's dashes array, the returned dashes are truncated to dashesCount. If this value is greater than the number of dashes in the stroke style's dashes array, the extra dashes are set to 0.0f. To obtain the actual number of dashes in the stroke style's dashes array, use the GetDashesCount method.
The dashes are specified in units that are a multiple of the stroke width, with subsequent members of the array indicating the dashes and gaps between dashes: the first entry indicates a filled dash, the second a gap, and so on.
-Retrieves the type of shape used at the beginning of a stroke.
-Retrieves the type of shape used at the end of a stroke.
-Gets a value that specifies how the ends of each dash are drawn.
-Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
-Retrieves the type of joint used at the vertices of a shape's outline.
-Retrieves a value that specifies how far in the dash sequence the stroke will start.
-Gets a value that describes the stroke's dash pattern.
-If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
-Retrieves the number of entries in the dashes array.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the stroke transform type.
-This method returns the stroke transform type.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the stroke transform type.
-Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
-You create an
if (SUCCEEDED(hr))
- { hr = g_pGdiInterop->CreateBitmapRenderTarget(hdc, r.right, r.bottom, &g_pBitmapRenderTarget);
- }
-
One way to use a
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, DWRITE_MEASURING_MODE measuringMode, __in DWRITE_GLYPH_RUN const* glyphRun, __in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription, IUnknown* clientDrawingEffect )
- { HRESULT hr = S_OK; // Pass on the drawing call to the render target to do the real work. RECT dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;
- }
-
- The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not. Default rendering params can be retrieved by using the Draws a run of glyphs to a bitmap target at the specified position.
-The horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The measuring method for glyphs in the run, used with the other properties to determine the rendering mode.
The structure containing the properties of the glyph run.
The object that controls rendering behavior.
The foreground color of the text.
The optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.
If this method succeeds, it returns
You can use the
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not.
Default rendering params can be retrieved by using the
Gets a handle to the memory device context.
-Returns a device context handle to the memory device context.
An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets the number of bitmap pixels per DIP.
-The number of bitmap pixels per DIP.
A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Sets the number of bitmap pixels per DIP (device-independent pixel). A DIP is 1/96 inch, so this value is the number if pixels per inch divided by 96.
-A value that specifies the number of pixels per DIP.
If this method succeeds, it returns
Gets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-When this method returns, contains a transform matrix.
If this method succeeds, it returns
Sets the transform that maps abstract coordinate to DIPs (device-independent pixel). This does not affect the world transform of the underlying device context.
- Specifies the new transform. This parameter can be
If this method succeeds, it returns
Gets the dimensions of the target bitmap.
-Returns the width and height of the bitmap in pixels.
If this method succeeds, it returns
Resizes the bitmap.
-The new bitmap width, in pixels.
The new bitmap height, in pixels.
If this method succeeds, it returns
Gets a handle to the memory device context.
- An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();
- The
Gets or sets the number of bitmap pixels per DIP.
-A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
-Gets or sets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
-Gets the dimensions of the target bitmap.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
-Wraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
- The application implemented rendering callback (
If this method succeeds, it returns
If this method succeeds, it returns
TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object. In the case of a simple bitmap, with no padding and no overhang, all the overhangs will simply be zeroes.
The overhangs should be returned relative to the reported size of the object (see
If this method succeeds, it returns
Layout uses this to determine the line-breaking behavior of the inline object among the text.
-When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately preceding it.
When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately following it.
If this method succeeds, it returns
Used to create all subsequent DirectWrite objects. This interface is the root factory interface for all DirectWrite objects.
- Create an
if (SUCCEEDED(hr))
- { hr = An
Gets an object which represents the set of installed fonts.
-If this parameter is nonzero, the function performs an immediate check for changes to the set of installed fonts. If this parameter is
When this method returns, contains the address of a reference to the system font collection object, or
Creates a font collection using a custom font collection loader.
-An application-defined font collection loader, which must have been previously registered using RegisterFontCollectionLoader.
The key used by the loader to identify a collection of font files. The buffer allocated for this key should at least be the size of collectionKeySize.
The size, in bytes, of the collection key.
Contains an address of a reference to the system font collection object if the method succeeds, or
If this method succeeds, it returns
Registers a custom font collection loader with the factory object.
-Pointer to a
If this method succeeds, it returns
This function registers a font collection loader with DirectWrite. The font collection loader interface, which should be implemented by a singleton object, handles enumerating font files in a font collection given a particular type of key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
-If this method succeeds, it returns
Creates a font file reference object from a local font file.
-An array of characters that contains the absolute file path for the font file. Subsequent operations on the constructed object may fail if the user provided filePath doesn't correspond to a valid file on the disk.
The last modified time of the input file path. If the parameter is omitted, the function will access the font file to obtain its last write time. You should specify this value to avoid extra disk access. Subsequent operations on the constructed object may fail if the user provided lastWriteTime doesn't match the file on the disk.
When this method returns, contains an address of a reference to the newly created font file reference object, or
If this method succeeds, it returns
Creates a reference to an application-specific font file resource.
-A font file reference key that uniquely identifies the font file resource during the lifetime of fontFileLoader.
The size of the font file reference key in bytes.
The font file loader that will be used by the font system to load data from the file identified by fontFileReferenceKey.
Contains an address of a reference to the newly created font file object when this method succeeds, or
If this method succeeds, it returns
This function is provided for cases when an application or a document needs to use a private font without having to install it on the system. fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
-Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates an object that represents a font face.
-A value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates a rendering parameters object with default settings for the primary monitor. Different monitors may have different rendering parameters, for more information see the How to Add Support for Multiple Monitors topic.
-Standard
Creates a rendering parameters object with default settings for the specified monitor. In most cases, this is the preferred way to create a rendering parameters object.
-A handle for the specified monitor.
When this method returns, contains an address of a reference to the rendering parameters object created by this method.
If this method succeeds, it returns
Creates a rendering parameters object with the specified properties.
-The gamma level to be set for the new rendering parameters object.
The enhanced contrast level to be set for the new rendering parameters object.
The ClearType level to be set for the new rendering parameters object.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.
A value that represents the method (for example, ClearType natural quality) for rendering glyphs.
When this method returns, contains an address of a reference to the newly created rendering parameters object.
If this method succeeds, it returns
Registers a font file loader with DirectWrite.
-Pointer to a
If this method succeeds, it returns
This function registers a font file loader with DirectWrite. The font file loader interface, which should be implemented by a singleton object, handles loading font file resources of a particular type from a key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
-Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
-If this method succeeds, it returns
This function unregisters font file loader callbacks with the DirectWrite font system. You should implement the font file loader interface by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite should be performed outside of the font file loader implementation.
-Creates a text format object used for text layout.
-An array of characters that contains the name of the font family
A reference to a font collection object. When this is
A value that indicates the font weight for the text object created by this method.
A value that indicates the font style for the text object created by this method.
A value that indicates the font stretch for the text object created by this method.
The logical size of the font in DIP ("device-independent pixel") units. A DIP equals 1/96 inch.
An array of characters that contains the locale name.
When this method returns, contains an address of a reference to a newly created text format object, or
If this method succeeds, it returns
Creates a typography object for use in a text layout.
-When this method returns, contains the address of a reference to a newly created typography object, or
If this method succeeds, it returns
Creates an object that is used for interoperability with GDI.
-When this method returns, contains an address of a reference to a GDI interop object if successful, or
If this method succeeds, it returns
Takes a string, text format, and associated constraints, and produces an object that represents the fully analyzed and formatted result.
-An array of characters that contains the string to create a new
The number of characters in the string.
A reference to an object that indicates the format to apply to the string.
The width of the layout box.
The height of the layout box.
When this method returns, contains an address of a reference to the resultant text layout object.
If this method succeeds, it returns
Takes a string, format, and associated constraints, and produces an object representing the result, formatted for a particular display resolution and measuring mode.
-An array of characters that contains the string to create a new
The length of the string, in character count.
The text formatting object to apply to the string.
The width of the layout box.
The height of the layout box.
The number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI device pixelsPerDip is 1. If rendering onto a 120 DPI device pixelsPerDip is 1.25 (120/96).
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specifies the font size and pixels per DIP.
Instructs the text layout to use the same metrics as GDI bi-level text when set to
When this method returns, contains an address to the reference of the resultant text layout object.
If this method succeeds, it returns
The resulting text layout should only be used for the intended resolution, and for cases where text scalability is desired CreateTextLayout should be used instead.
-Creates an inline object for trimming, using an ellipsis as the omission sign.
-A text format object, created with CreateTextFormat, used for text layout.
When this method returns, contains an address of a reference to the omission (that is, ellipsis trimming) sign created by this method.
If this method succeeds, it returns
The ellipsis will be created using the current settings of the format, including base font, style, and any effects. Alternate omission signs can be created by the application by implementing
Returns an interface for performing text analysis.
-When this method returns, contains an address of a reference to the newly created text analyzer object.
If this method succeeds, it returns
Creates a number substitution object using a locale name, substitution method, and an indicator whether to ignore user overrides (use NLS defaults for the given culture instead).
-A value that specifies how to apply number substitution on digits and related punctuation.
The name of the locale to be used in the numberSubstitution object.
A Boolean flag that indicates whether to ignore user overrides.
When this method returns, contains an address to a reference to the number substitution object created by this method.
If this method succeeds, it returns
Creates a glyph run analysis object, which encapsulates information used to render a glyph run.
-A structure that contains the properties of the glyph run (font face, advances, and so on).
Number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI bitmap then pixelsPerDip is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 1.25.
Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified the emSize and pixelsPerDip.
A value that specifies the rendering mode, which must be one of the raster rendering modes (that is, not default and not outline).
Specifies the measuring mode to use with glyphs.
The horizontal position (X-coordinate) of the baseline origin, in DIPs.
Vertical position (Y-coordinate) of the baseline origin, in DIPs.
When this method returns, contains an address of a reference to the newly created glyph run analysis object.
If this method succeeds, it returns
The glyph run analysis object contains the results of analyzing the glyph run, including the positions of all the glyphs and references to all of the rasterized glyphs in the font cache.
-Creates an object that is used for interoperability with GDI.
-An object that encapsulates a set of fonts, such as the set of fonts installed on the system, or the set of fonts in a particular directory. The font collection API can be used to discover what font families and fonts are available, and to obtain some metadata about the fonts.
-The
null ; // Get the system font collection.
- if (SUCCEEDED(hr))
- { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection);
- }
-
To determine what fonts are available on the system, get a reference to the system font collection. You can then use the
#include <dwrite.h>
- #include <string.h>
- #include <stdio.h>
- #include <new> // SafeRelease inline function.
- template <class T> inline void SafeRelease(T **ppT)
- { if (*ppT) { (*ppT)->Release(); *ppT = null ; }
- } void wmain()
- { null ; null ; // Get the system font collection. if (SUCCEEDED(hr)) { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection); } UINT32 familyCount = 0; // Get the number of font families in the collection. if (SUCCEEDED(hr)) { familyCount = pFontCollection->GetFontFamilyCount(); } for (UINT32 i = 0; i < familyCount; ++i) { null ; // Get the font family. if (SUCCEEDED(hr)) { hr = pFontCollection->GetFontFamily(i, &pFontFamily); } null ; // Get a list of localized strings for the family name. if (SUCCEEDED(hr)) { hr = pFontFamily->GetFamilyNames(&pFamilyNames); } UINT32 index = 0; null ) { hr = E_OUTOFMEMORY; } // Get the family name. if (SUCCEEDED(hr)) { hr = pFamilyNames->GetString(index, name, length+1); } if (SUCCEEDED(hr)) { // Print out the family name. wprintf(L"%s\n", name); } SafeRelease(&pFontFamily); SafeRelease(&pFamilyNames); delete [] name; } SafeRelease(&pFontCollection); SafeRelease(&pDWriteFactory);
- } Gets the number of font families in the collection.
-The number of font families in the collection.
Creates a font family object given a zero-based font family index.
-Zero-based index of the font family.
When this method returns, contains the address of a reference to the newly created font family object.
Finds the font family with the specified family name.
-An array of characters, which is null-terminated, containing the name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.
When this method returns, contains the zero-based index of the matching font family if the family name was found; otherwise, UINT_MAX.
When this method returns, TRUE if the family name exists; otherwise,
Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong to the font collection.
-A font face object that specifies the physical font.
When this method returns, contains the address of a reference to the newly created font object if successful; otherwise,
Gets the number of font families in the collection.
-Used to construct a collection of fonts given a particular type of key.
-The font collection loader interface is recommended to be implemented by a singleton object. Note that font collection loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Represents an absolute reference to a font face which contains font face type, appropriate file references, face identification data and various font data such as metrics, names and glyph outlines.
-Obtains the file format type of a font face.
-A value that indicates the type of format for the font face (such as Type 1, TrueType, vector, or bitmap).
Obtains the font files representing a font face.
-If fontFiles is
When this method returns, contains a reference to a user-provided array that stores references to font files representing the font face. This parameter can be
If this method succeeds, it returns
The
Then, call the method a second time, passing the numberOfFiles value that was output the first call, and a non-null buffer of the correct size to store the
Obtains the index of a font face in the context of its font files.
-The zero-based index of a font face in cases when the font files contain a collection of font faces. If the font files contain a single face, this value is zero.
Obtains the algorithmic style simulation flags of a font face.
-Font face simulation flags for algorithmic means of making text bold or italic.
Determines whether the font is a symbol font.
-Returns TRUE if the font is a symbol font, otherwise
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, a?
Obtains the number of glyphs in the font face.
-The number of glyphs in the font face.
Obtains ideal (resolution-independent) glyph metrics in font design units.
-An array of glyph indices for which to compute metrics. The array must contain at least as many elements as specified by glyphCount.
The number of elements in the glyphIndices array.
When this method returns, contains an array of
Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation
If this method succeeds, it returns
Design glyph metrics are used for glyph positioning.
-Returns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.
-An array of USC4 code points from which to obtain nominal glyph indices. The array must be allocated and be able to contain the number of elements specified by codePointCount.
The number of elements in the codePoints array.
When this method returns, contains a reference to an array of nominal glyph indices filled by this function.
If this method succeeds, it returns
Note that this mapping is primarily provided for line layout engines built on top of the physical font API. Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond to how a Unicode string will map to glyph indices when rendering using a particular font face. Also, note that Unicode variant selectors provide for alternate mappings for character to glyph. This call will always return the default variant.
- Finds the specified OpenType font table if it exists and returns a reference to it. The function accesses the underlying font data through the
If this method succeeds, it returns
The context for the same tag may be different for each call, so each one must be held and released separately.
-Releases the table obtained earlier from TryGetFontTable.
-Computes the outline of a run of glyphs by calling back to the outline sink interface.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
An array of glyph indices. The glyphs are in logical order and the advance direction depends on the isRightToLeft parameter. The array must be allocated and be able to contain the number of elements specified by glyphCount.
An optional array of glyph advances in DIPs. The advance of a glyph is the amount to advance the position (in the direction of the baseline) after drawing the glyph. glyphAdvances contains the number of elements specified by glyphCount.
An optional array of glyph offsets, each of which specifies the offset along the baseline and offset perpendicular to the baseline of a glyph relative to the current pen position. glyphOffsets contains the number of elements specified by glyphCount.
The number of glyphs in the run.
If TRUE, the ascender of the glyph runs alongside the baseline. If
A client can render a vertical run by setting isSideways to TRUE and rotating the resulting geometry 90 degrees to the right using a transform. The isSideways and isRightToLeft parameters cannot both be true.
The visual order of the glyphs. If this parameter is
A reference to the interface that is called back to perform outline drawing operations.
If this method succeeds, it returns
Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
The number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:
A reference to an object that contains rendering settings such as gamma level, enhanced contrast, and ClearType level. This parameter is necessary in case the rendering parameters object overrides the rendering mode.
When this method returns, contains a value that indicates the recommended rendering mode to use.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
-The logical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
A reference to a DWRITE_FONT_METRICS structure to fill in. The metrics returned by this function are in font design units.
Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.
-The ogical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
When set to
An array of glyph indices for which to compute the metrics.
The number of elements in the glyphIndices array.
An array of
A
Standard
Obtains the file format type of a font face.
-Obtains the index of a font face in the context of its font files.
-Obtains the algorithmic style simulation flags of a font face.
-Determines whether the font is a symbol font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Obtains the number of glyphs in the font face.
-Specifies properties used to identify and execute typographic features in the current font face.
-A non-zero value generally enables the feature execution, while the zero value disables it. A feature requiring a selector uses this value to indicate the selector index.
The OpenType standard provides access to typographic features available in the font by means of a feature tag with the associated parameters. The OpenType feature tag is a 4-byte identifier of the registered name of a feature. For example, the 'kern' feature name tag is used to identify the 'Kerning' feature in OpenType font. Similarly, the OpenType feature tag for 'Standard Ligatures' and 'Fractions' is 'liga' and 'frac' respectively. Since a single run can be associated with more than one typographic features, the Text String API accepts typographic settings for a run as a list of features and are executed in the order they are specified.
The value of the tag member represents the OpenType name tag of the feature, while the param value represents additional parameter for the execution of the feature referred by the tag member. Both nameTag and parameter are stored as little endian, the same convention followed by GDI. Most features treat the Param value as a binary value that indicates whether to turn the execution of the feature on or off, with it being off by default in the majority of cases. Some features, however, treat this value as an integral value representing the integer index to the list of alternate results it may produce during the execution; for instance, the feature 'Stylistic Alternates' or 'salt' uses the parameter value as an index to the list of alternate substituting glyphs it could produce for a specified glyph.
-The feature OpenType name identifier.
The execution parameter of the feature.
Represents a font file. Applications such as font managers or font viewers can call
Obtains the reference to the reference key of a font file. The returned reference is valid until the font file object is released.
-When this method returns, contains an address of a reference to the font file reference key. Note that the reference value is only valid until the font file object it is obtained from is released. This parameter is passed uninitialized.
When this method returns, contains the size of the font file reference key in bytes. This parameter is passed uninitialized.
If this method succeeds, it returns
Obtains the file loader associated with a font file object.
-When this method returns, contains the address of a reference to the font file loader associated with the font file object.
If this method succeeds, it returns
Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
-TRUE if the font type is supported by the font system; otherwise,
When this method returns, contains a value that indicates the type of the font file. Note that even if isSupportedFontType is
When this method returns, contains a value that indicates the type of the font face. If fontFileType is not equal to
When this method returns, contains the number of font faces contained in the font file.
If this method succeeds, it returns
Important??Certain font file types are recognized, but not supported by the font system. For example, the font system will recognize a file as a Type 1 font file but will not be able to construct a font face object from it. In such situations, Analyze will set isSupportedFontType output parameter to
Encapsulates a collection of font files. The font system uses this interface to enumerate font files when building a font collection.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Handles loading font file resources of a particular type from a font file reference key into a font file stream object.
-The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
-Creates a font file stream object that encapsulates an open file resource.
-A reference to a font file reference key that uniquely identifies the font file resource within the scope of the font loader being used. The buffer allocated for this key must at least be the size, in bytes, specified by fontFileReferenceKeySize.
The size of font file reference key, in bytes.
When this method returns, contains the address of a reference to the newly created
If this method succeeds, it returns
The resource is closed when the last reference to fontFileStream is released.
-Loads font file data from a custom font file loader.
-Loads font file data from a custom font file loader.
-Reads a fragment from a font file.
-When this method returns, contains an address of a reference to the start of the font file fragment. This parameter is passed uninitialized.
The offset of the fragment, in bytes, from the beginning of the font file.
The size of the file fragment, in bytes.
When this method returns, contains the address of a reference to a reference to the client-defined context to be passed to ReleaseFileFragment.
If this method succeeds, it returns
Note that ReadFileFragment implementations must check whether the requested font file fragment is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
DirectWrite may invoke
Releases a fragment from a file.
-A reference to the client-defined context of a font fragment returned from ReadFileFragment.
Obtains the total size of a file.
-When this method returns, contains the total size of the file.
If this method succeeds, it returns
Implementing GetFileSize() for asynchronously loaded font files may require downloading the complete file contents. Therefore, this method should be used only for operations that either require a complete font file to be loaded (for example, copying a font file) or that need to make decisions based on the value of the file size (for example, validation against a persisted file size).
-Obtains the last modified time of the file.
-When this method returns, contains the last modified time of the file in the format that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC).
If this method succeeds, it returns
The "last modified time" is used by DirectWrite font selection algorithms to determine whether one font resource is more up to date than another one.
-Provides interoperability with GDI, such as methods to convert a font face to a
Creates a font object that matches the properties specified by the
A structure containing a GDI-compatible font description.
When this method returns, contains an address of a reference to a newly created
If this method succeeds, it returns
Initializes a
An
When this method returns, contains a structure that receives a GDI-compatible font description.
When this method returns, contains TRUE if the specified font object is part of the system font collection; otherwise,
If this method succeeds, it returns
The conversion to a
Initializes a
An
When this method returns, contains a reference to a structure that receives a GDI-compatible font description.
If this method succeeds, it returns
The conversion to a
Creates an
A handle to a device context into which a font has been selected. It is assumed that the client has already performed font mapping and that the font selected into the device context is the actual font to be used for rendering glyphs.
Contains an address of a reference to the newly created font face object, or
This function is intended for scenarios in which an application wants to use GDI and Uniscribe 1.x for text layout and shaping, but DirectWrite for final rendering. This function assumes the client is performing text output using glyph indexes.
-Creates an object that encapsulates a bitmap and memory DC (device context) which can be used for rendering glyphs.
-A handle to the optional device context used to create a compatible memory DC (device context).
The width of the bitmap render target.
The height of the bitmap render target.
When this method returns, contains an address of a reference to the newly created
Contains the information needed by renderers to draw glyph runs. All coordinates are in device independent pixels (DIPs).
-The physical font face object to draw with.
The logical size of the font in DIPs (equals 1/96 inch), not points.
The number of glyphs in the glyph run.
A reference to an array of indices to render for the glyph run.
A reference to an array containing glyph advance widths for the glyph run.
A reference to an array containing glyph offsets for the glyph run.
If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used. Vertical writing is achieved by specifying isSideways = true and rotating the entire run 90 degrees to the right via a rotate transform.
The implicit resolved bidi level of the run. Odd levels indicate right-to-left languages like Hebrew and Arabic, while even levels indicate left-to-right languages like English and Japanese (when written horizontally). For right-to-left languages, the text origin is on the right, and text should be drawn to the left.
Contains low-level information used to render a glyph run.
-The alpha texture can be a bi-level alpha texture or a ClearType alpha texture.
A bi-level alpha texture contains one byte per pixel, therefore the size of the buffer for a bi-level texture will be the area of the texture bounds, in bytes. Each byte in a bi-level alpha texture created by CreateAlphaTexture is either set to DWRITE_ALPHA_MAX (that is, 255) or zero.
A ClearType alpha texture contains three bytes per pixel, therefore the size of the buffer for a ClearType alpha texture is three times the area of the texture bounds, in bytes.
-Gets the bounding rectangle of the physical pixels affected by the glyph run.
-Specifies the type of texture requested. If a bi-level texture is requested, the bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only antialiased glyphs.
When this method returns, contains the bounding rectangle of the physical pixels affected by the glyph run, or an empty rectangle if there are no glyphs of the specified texture type.
Creates an alpha texture of the specified type for glyphs within a specified bounding rectangle.
-A value that specifies the type of texture requested. This can be DWRITE_TEXTURE_BILEVEL_1x1 or
The bounding rectangle of the texture, which can be different than the bounding rectangle returned by GetAlphaTextureBounds.
When this method returns, contains the array of alpha values from the texture. The buffer allocated for this array must be at least the size of bufferSize.
The size of the alphaValues array, in bytes. The minimum size depends on the dimensions of the rectangle and the type of texture requested.
If this method succeeds, it returns
Gets alpha blending properties required for ClearType blending.
-An object that specifies the ClearType level and enhanced contrast, gamma, pixel geometry, and rendering mode. In most cases, the values returned by the output parameters of this method are based on the properties of this object, unless a GDI-compatible rendering mode was specified.
When this method returns, contains the gamma value to use for gamma correction.
When this method returns, contains the enhanced contrast value to be used for blending.
When this method returns, contains the ClearType level used in the alpha blending.
If this method succeeds, it returns
Contains additional properties related to those in
An array of characters containing the locale name associated with this run.
An array of characters containing the text associated with the glyphs.
The number of characters in UTF16 code-units. Note that this may be different than the number of glyphs.
An array of indices to the glyph indices array, of the first glyphs of all the glyph clusters of the glyphs to render.
Corresponding text position in the string this glyph run came from. This is relative to the beginning of the string represented by the
Line breakpoint characteristics of a character.
-Indicates a breaking condition before the character.
Indicates a breaking condition after the character.
Indicates that the character is some form of whitespace, which may be meaningful for justification.
Indicates that the character is a soft hyphen, often used to indicate hyphenation points inside words.
Reserved for future use.
Represents a collection of strings indexed by locale name.
-The set of strings represented by an
A common use for the
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-The number of language/string pairs.
Gets the zero-based index of the locale name/string pair with the specified locale name.
-A null-terminated array of characters containing the locale name to look for.
The zero-based index of the locale name/string pair. This method initializes index to UINT_MAX.
When this method returns, contains TRUE if the locale name exists; otherwise,
Note that if the locale name does not exist, the return value is a success and the exists parameter is
UINT32 index = 0;
- Gets the length in characters (not including the null terminator) of the locale name with the specified index.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains the length in characters of the locale name, not including the null terminator.
If this method succeeds, it returns
Copies the locale name with the specified index to the specified array.
-Zero-based index of the locale name to be retrieved.
When this method returns, contains a character array, which is null-terminated, that receives the locale name from the language/string pair. The buffer allocated for this array must be at least the size of size, in element count.
The size of the array in characters. The size must include space for the terminating null character.
If this method succeeds, it returns
Gets the length in characters (not including the null terminator) of the string with the specified index.
-A zero-based index of the language/string pair.
The length in characters of the string, not including the null terminator, from the language/string pair.
If this method succeeds, it returns
Use GetStringLength to get the string length before calling the
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Copies the string with the specified index to the specified array.
-The zero-based index of the language/string pair to be examined.
The null terminated array of characters that receives the string from the language/string pair. The buffer allocated for this array should be at least the size of size. GetStringLength can be used to get the size of the array before using this method.
The size of the array in characters. The size must include space for the terminating null character. GetStringLength can be used to get the size of the array before using this method.
If this method succeeds, it returns
The string returned must be allocated by the caller. You can get the size of the string by using the GetStringLength method prior to calling GetString, as shown in the following example.
UINT32 length = 0; // Get the string length.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetStringLength(index, &length);
- } // Allocate a string big enough to hold the name.
- wchar_t* name = new (std::nothrow) wchar_t[length+1];
- if (name == null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the number of language/string pairs.
-Holds the appropriate digits and numeric punctuation for a specified locale.
-Defines the pixel snapping properties such as pixels per DIP(device-independent pixel) and the current transform matrix of a text renderer.
-Represents text rendering settings such as ClearType level, enhanced contrast, and gamma correction for glyph rasterization and filtering.
An application typically obtains a rendering parameters object by calling the
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-Returns the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Returns the amount of contrast enhancement. Valid values are greater than or equal to zero.
Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level of the rendering parameters object.
The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-A value that indicates the type of pixel geometry used in the rendering parameters object.
Gets the rendering mode of the rendering parameters object.
-A value that indicates the rendering mode of the rendering parameters object.
By default, the rendering mode is initialized to
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
-The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
-Gets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
-Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
-Gets the ClearType level of the rendering parameters object.
-The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
-Gets the pixel geometry of the rendering parameters object.
-Gets the rendering mode of the rendering parameters object.
-By default, the rendering mode is initialized to
Contains shaping output properties for an output glyph.
-Indicates that the glyph has justification applied.
Indicates that the glyph is the start of a cluster.
Indicates that the glyph is a diacritic mark.
Indicates that the glyph is a word boundary with no visible space.
Reserved for future use.
The
To get a reference to the
if (SUCCEEDED(hr))
- { hr = pDWriteFactory_->CreateTextFormat( L"Gabriola", null , When creating an
These properties cannot be changed after the
The
To draw text with multiple formats, or to use a custom text renderer, use the
This object may not be thread-safe, and it may carry the state of text format change.
DirectWrite and Direct2D To draw simple text with a single format, Direct2D provides the
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the alignment of text in a paragraph, relative to the leading and trailing edge of a layout box for a
This method can return one of the following values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| The textAlignment argument is invalid. |
?
The text can be aligned to the leading or trailing edge of the layout box, or it can be centered. The following illustration shows text with the alignment set to
Note??The alignment is dependent on reading direction, the above is for left-to-right reading direction. For right-to-left reading direction it would be the opposite.
See
Sets the alignment option of a paragraph relative to the layout box's top and bottom edge.
-The paragraph alignment option being set for a paragraph; see
If this method succeeds, it returns
Sets the word wrapping option.
-The word wrapping option being set for a paragraph; see
If this method succeeds, it returns
Sets the paragraph reading direction.
-The text reading direction (for example,
If this method succeeds, it returns
Sets the paragraph flow direction.
-The paragraph flow direction; see
If this method succeeds, it returns
Sets a fixed distance between two adjacent tab stops.
-The fixed distance between two adjacent tab stops.
If this method succeeds, it returns
Sets trimming options for text overflowing the layout width.
-Text trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the line spacing.
-Specifies how line height is being determined; see
The line height, or distance between one baseline to another.
The distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
For the default method, spacing depends solely on the content. For uniform spacing, the specified line height overrides the content.
-Gets the alignment option of text relative to the layout box's leading and trailing edge.
-Returns the text alignment option of the current paragraph.
Gets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-A value that indicates the current paragraph alignment option.
Gets the word wrapping option.
-Returns the word wrapping option; see
Gets the current reading direction for text in a paragraph.
-A value that indicates the current reading direction for text in a paragraph.
Gets the direction that text lines flow.
-The direction that text lines flow within their parent container. For example,
Gets the incremental tab stop position.
-The incremental tab stop value.
Gets the trimming options for text that overflows the layout box.
-When this method returns, it contains a reference to a
When this method returns, contains an address of a reference to a trimming omission sign. This parameter may be
If this method succeeds, it returns
Gets the line spacing adjustment set for a multiline text paragraph.
-A value that indicates how line height is determined.
When this method returns, contains the line height, or distance between one baseline to another.
When this method returns, contains the distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
Gets the current font collection.
-When this method returns, contains an address of a reference to the font collection being used for the current text.
If this method succeeds, it returns
Gets the length of the font family name.
-The size of the character array, in character count, not including the terminated
Gets a copy of the font family name.
-When this method returns, contains a reference to a character array, which is null-terminated, that receives the current font family name. The buffer allocated for this array should be at least the size, in elements, of nameSize.
The size of the fontFamilyName character array, in character count, including the terminated
If this method succeeds, it returns
Gets the font weight of the text.
-A value that indicates the type of weight (such as normal, bold, or black).
Gets the font style of the text.
-A value which indicates the type of font style (such as slope or incline).
Gets the font stretch of the text.
-A value which indicates the type of font stretch (such as normal or condensed).
Gets the font size in DIP unites.
-The current font size in DIP units.
Gets the length of the locale name.
-The size of the character array in character count, not including the terminated
Gets a copy of the locale name.
-Contains a character array that receives the current locale name.
The size of the character array, in character count, including the terminated
If this method succeeds, it returns
Gets or sets the alignment option of text relative to the layout box's leading and trailing edge.
-Gets or sets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
-Gets or sets the word wrapping option.
-Gets or sets the current reading direction for text in a paragraph.
-Gets or sets the direction that text lines flow.
-Gets or sets the incremental tab stop position.
-Gets the current font collection.
-Gets the font weight of the text.
-Gets the font style of the text.
-Gets the font stretch of the text.
-Gets the font size in DIP unites.
-The
To get a reference to the
// Create a text layout using the text format.
- if (SUCCEEDED(hr))
- { The
// Set the font weight to bold for the first 5 letters.
- To draw the block of text represented by an
To draw a formatted string represented by an
To render using a custom renderer, use the
// Draw the text layout using DirectWrite and the CustomTextRenderer class.
- hr = pTextLayout_->Draw( null , pTextRenderer_, // Custom text renderer. origin.x, origin.y );
Using a custom text renderer also enables you to render using another technology, such as GDI.
-Sets the layout maximum width.
-A value that indicates the maximum width of the layout box.
If this method succeeds, it returns
Sets the layout maximum height.
-A value that indicates the maximum height of the layout box.
If this method succeeds, it returns
Sets the font collection.
-The font collection to set.
Text range to which this change applies.
If this method succeeds, it returns
Sets null-terminated font family name for text within a specified text range.
-The font family name that applies to the entire text string within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font weight for text within a text range specified by a
If this method succeeds, it returns
The font weight can be set to one of the predefined font weight values provided in the
The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
- Sets the font style for text within a text range specified by a
If this method succeeds, it returns
The font style can be set to Normal, Italic or Oblique. The following illustration shows three styles for the Palatino font. For more information, see
Sets the font stretch for text within a specified text range.
-A value which indicates the type of font stretch for text within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font size in DIP units for text within a specified text range.
-The font size in DIP units to be set for text in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets underlining for text within a specified text range.
-A Boolean flag that indicates whether underline takes place within a specified text range.
Text range to which this change applies.
If this method succeeds, it returns
Sets strikethrough for text within a specified text range.
-A Boolean flag that indicates whether strikethrough takes place in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the application-defined drawing effect.
-Application-defined drawing effects that apply to the range. This data object will be passed back to the application's drawing callbacks for final rendering.
The text range to which this change applies.
If this method succeeds, it returns
An
This drawing effect is associated with the specified range and will be passed back to the application by way of the callback when the range is drawn at drawing time.
-Sets the inline object.
-An application-defined inline object.
Text range to which this change applies.
If this method succeeds, it returns
The application may call this function to specify the set of properties describing an application-defined inline object for specific range.
This inline object applies to the specified range and will be passed back to the application by way of the DrawInlineObject callback when the range is drawn. Any text in that range will be suppressed.
-Sets font typography features for text within a specified text range.
-Pointer to font typography settings.
Text range to which this change applies.
If this method succeeds, it returns
Sets the locale name for text within a specified text range.
-A null-terminated locale name string.
Text range to which this change applies.
If this method succeeds, it returns
Gets the layout maximum width.
-Returns the layout maximum width.
Gets the layout maximum height.
-The layout maximum height.
Gets the font collection associated with the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
Contains an address of a reference to the current font collection.
Get the length of the font family name at the current position.
-The current text position.
When this method returns, contains the size of the character array containing the font family name, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family.
If this method succeeds, it returns
Copies the font family name of the text at the specified position.
-The position of the text to examine.
When this method returns, contains an array of characters that receives the current font family name. You must allocate storage for this parameter.
The size of the character array in character count including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family name.
If this method succeeds, it returns
Gets the font weight of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font weight.
When this method returns, contains a value which indicates the type of font weight being applied at the specified position.
Gets the font style (also known as slope) of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font style.
When this method returns, contains a value which indicates the type of font style (also known as slope or incline) being applied at the specified position.
Gets the font stretch of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font stretch.
When this method returns, contains a value which indicates the type of font stretch (also known as width) being applied at the specified position.
Gets the font em height of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font size.
When this method returns, contains the size of the font in ems of the text at the specified position.
Gets the underline presence of the text at the specified position.
-The current text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
A Boolean flag that indicates whether underline is present at the position indicated by currentPosition.
Get the strikethrough presence of the text at the specified position.
-The position of the text to inspect.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to strikethrough.
A Boolean flag that indicates whether strikethrough is present at the position indicated by currentPosition.
Gets the application-defined drawing effect at the specified text position.
-The position of the text whose drawing effect is to be retrieved.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the drawing effect.
When this method returns, contains an address of a reference to the current application-defined drawing effect. Usually this effect is a foreground brush that is used in glyph drawing.
Gets the inline object at the specified position.
-The specified text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the inline object.
Contains the application-defined inline object.
Gets the typography setting of the text at the specified position.
-The position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the typography.
When this method returns, contains an address of a reference to the current typography setting.
Gets the length of the locale name of the text at the specified position.
-The position of the text to inspect.
Size of the character array, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Gets the locale name of the text at the specified position.
-The position of the text to inspect.
When this method returns, contains the character array receiving the current locale name.
Size of the character array, in character count, including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Draws text using the specified client drawing context.
-An application-defined drawing context.
Pointer to the set of callback functions used to draw parts of a text string.
The x-coordinate of the layout's left side.
The y-coordinate of the layout's top side.
If this method succeeds, it returns
To draw text with this method, a textLayout object needs to be created by the application using
After the textLayout object is obtained, the application calls the
Retrieves the information about each individual text line of the text string.
-When this method returns, contains a reference to an array of structures containing various calculated length values of individual text lines.
The maximum size of the lineMetrics array.
When this method returns, contains the actual size of the lineMetrics array that is needed.
If this method succeeds, it returns
If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Retrieves overall metrics for the formatted string.
-When this method returns, contains the measured distances of text and associated content after being formatted.
If this method succeeds, it returns
Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Overshoots of visible extents (in DIPs) outside the layout.
If this method succeeds, it returns
Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Retrieves logical properties and measurements of each glyph cluster.
-When this method returns, contains metrics, such as line-break or total advance width, for a glyph cluster.
The maximum size of the clusterMetrics array.
When this method returns, contains the actual size of the clusterMetrics array that is needed.
If this method succeeds, it returns
If maxClusterCount is not large enough, then E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
-Minimum width.
The application calls this function passing in a specific pixel location relative to the top-left location of the layout box and obtains the information about the correspondent hit-test metrics of the text string where the hit-test has occurred. When the specified pixel location is outside the text string, the function sets the output value *isInside to
The pixel location X to hit-test, relative to the top-left location of the layout box.
The pixel location Y to hit-test, relative to the top-left location of the layout box.
An output flag that indicates whether the hit-test location is at the leading or the trailing side of the character. When the output *isInside value is set to
An output flag that indicates whether the hit-test location is inside the text string. When
The output geometry fully enclosing the hit-test location. When the output *isInside value is set to
The application calls this function to get the pixel location relative to the top-left of the layout box given the text position and the logical side of the position. This function is normally used as part of caret positioning of text where the caret is drawn at the location corresponding to the current text editing position. It may also be used as a way to programmatically obtain the geometry of a particular text position in UI automation.
-The text position used to get the pixel location.
A Boolean flag that indicates whether the pixel location is of the leading or the trailing side of the specified text position.
When this method returns, contains the output pixel location X, relative to the top-left location of the layout box.
When this method returns, contains the output pixel location Y, relative to the top-left location of the layout box.
When this method returns, contains the output geometry fully enclosing the specified text position.
The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string. The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
The first text position of the specified range.
The number of positions of the specified range.
The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.
The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.
When this method returns, contains a reference to a buffer of the output geometry fully enclosing the specified position range. The buffer must be at least as large as maxHitTestMetricsCount.
Maximum number of boxes hitTestMetrics could hold in its buffer memory.
Actual number of geometries hitTestMetrics holds in its buffer memory.
If this method succeeds, it returns
Gets or sets the layout maximum width.
-Gets or sets the layout maximum height.
-Retrieves overall metrics for the formatted string.
-Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
-Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
-Specifies a range of text positions where format is applied in the text represented by an
Represents a set of application-defined callbacks that perform rendering of text, inline objects, and decorations such as underlines.
-Describes the pixel format and dpi of a bitmap.
-The bitmap's pixel format and alpha mode.
The horizontal dpi of the bitmap.
The vertical dpi of the bitmap.
Renders to an intermediate texture created by the CreateCompatibleRenderTarget method.
-An
To write directly to a WIC bitmap instead, use the
To create a bitmap render target, call the
Like other render targets, an
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-When this method returns, contains the address of a reference to the bitmap for this render target. This bitmap can be used for drawing operations.
If this method succeeds, it returns
The DPI for the
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
-The DPI for the
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Adds an OpenType font feature.
-A structure that contains the OpenType name identifier and the execution parameter for the font feature being added.
If this method succeeds, it returns
Gets the number of OpenType font features for the current font.
-The number of font features for the current text format.
A single run of text can be associated with more than one typographic feature. The
Gets the font feature at the specified index.
-The zero-based index of the font feature to retrieve.
When this method returns, contains the font feature which is at the specified index.
A single run of text can be associated with more than one typographic feature. The
Gets the number of OpenType font features for the current font.
-A single run of text can be associated with more than one typographic feature. The
Contains the center point, x-radius, and y-radius of an ellipse.
-The center point of the ellipse.
The X-radius of the ellipse.
The Y-radius of the ellipse.
The
The Roman baseline for horizontal; the Central baseline for vertical.
The baseline that is used by alphabetic scripts such as Latin, Greek, and Cyrillic.
Central baseline, which is generally used for vertical text.
Mathematical baseline, which math characters are centered on.
Hanging baseline, which is used in scripts like Devanagari.
Ideographic bottom baseline for CJK, left in vertical.
Ideographic top baseline for CJK, right in vertical.
The bottom-most extent in horizontal, left-most in vertical.
The top-most extent in horizontal, right-most in vertical.
Indicates the condition at the edges of inline object or text used to determine line-breaking behavior.
-Indicates whether a break is allowed by determining the condition of the neighboring text span or inline object.
Indicates that a line break is allowed, unless overruled by the condition of the neighboring text span or inline object, either prohibited by a "may not break" condition or forced by a "must break" condition.
Indicates that there should be no line break, unless overruled by a "must break" condition from the neighboring text span or inline object.
Indicates that the line break must happen, regardless of the condition of the adjacent text span or inline object.
Specifies the type of DirectWrite factory object.
-A DirectWrite factory object contains information about its internal state, such as font loader registration and cached font data. In most cases you should use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state information, thereby reducing memory usage. However, there are cases when it is desirable to reduce the impact of a component on the rest of the process, such as a plug-in from an untrusted source, by sandboxing and isolating it from the rest of the process components. In such cases, you should use an isolated factory for the sandboxed component.
-Indicates that the DirectWrite factory is a shared factory and that it allows for the reuse of cached font data across multiple in-process components. Such factories also take advantage of cross process font caching components for better performance.
Indicates that the DirectWrite factory object is isolated. Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
Indicates the direction of flow for placing lines of text in a paragraph.
-Specifies that text lines are placed from top to bottom.
Indicates the file format of a complete font face.
-Font formats that consist of multiple files, such as Type 1 .PFM and .PFB, have a single enum entry.
-OpenType font face with CFF outlines.
OpenType font face with TrueType outlines.
OpenType font face that is a part of a TrueType collection.
A Type 1 font face.
A vector .FON format font face.
A bitmap .FON format font face.
Font face type is not recognized by the DirectWrite font system.
A value that indicates the typographic feature of text supplied by the font.
-Replaces figures separated by a slash with an alternative form.
Equivalent OpenType tag: 'afrc'
Turns capital characters into petite capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in petite-cap form to avoid disrupting the flow of text. See the pcap feature description for notes on the relationship of caps, smallcaps and petite caps.
Equivalent OpenType tag: 'c2pc'
Turns capital characters into small capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in small-cap form to avoid disrupting the flow of text.
Equivalent OpenType tag: 'c2sc'
In specified situations, replaces default glyphs with alternate forms which provide better joining behavior. Used in script typefaces which are designed to have some or all of their glyphs join.
Equivalent OpenType tag: 'calt'
Shifts various punctuation marks up to a position that works better with all-capital sequences or sets of lining figures; also changes oldstyle figures to lining figures. By default, glyphs in a text face are designed to work with lowercase characters. Some characters should be shifted vertically to fit the higher visual center of all-capital or lining text. Also, lining figures are the same height (or close to it) as capitals, and fit much better with all-capital text.
Equivalent OpenType tag: 'case'
To minimize the number of glyph alternates, it is sometimes desired to decompose a character into two glyphs. Additionally, it may be preferable to compose two characters into a single glyph for better glyph processing. This feature permits such composition/decomposition. The feature should be processed as the first feature processed, and should be processed only when it is called.
Equivalent OpenType tag: 'ccmp'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. Unlike other ligature features, clig specifies the context in which the ligature is recommended. This capability is important in some script designs and for swash ligatures.
Equivalent OpenType tag: 'clig'
Globally adjusts inter-glyph spacing for all-capital text. Most typefaces contain capitals and lowercase characters, and the capitals are positioned to work with the lowercase. When capitals are used for words, they need more space between them for legibility and esthetics. This feature would not apply to monospaced designs. Of course the user may want to override this behavior in order to do more pronounced letterspacing for esthetic reasons.
Equivalent OpenType tag: 'cpsp'
Replaces default character glyphs with corresponding swash glyphs in a specified context. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'cswh'
In cursive scripts like Arabic, this feature cursively positions adjacent glyphs.
Equivalent OpenType tag: 'curs'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures which may be used for special effect, at the user's preference.
Equivalent OpenType tag: 'dlig'
Replaces standard forms in Japanese fonts with corresponding forms preferred by typographers. For example, a user would invoke this feature to replace kanji character U+5516 with U+555E. -
Equivalent OpenType tag: 'expt'
Replaces figures separated by a slash with 'common' (diagonal) fractions.
Equivalent OpenType tag: 'frac'
Replaces glyphs set on other widths with glyphs set on full (usually em) widths. In a CJKV font, this may include "lower ASCII" Latin characters and various symbols. In a European font, this feature replaces proportionally-spaced glyphs with monospaced glyphs, which are generally set on widths of 0.6 em. For example, a user may invoke this feature in a Japanese font to get full monospaced Latin glyphs instead of the corresponding proportionally-spaced versions.
Equivalent OpenType tag: 'fwid'
Produces the half forms of consonants in Indic scripts. For example, in Hindi (Devanagari script), the conjunct KKa, obtained by doubling the Ka, is denoted with a half form of Ka followed by the full form.
Equivalent OpenType tag: 'half'
Produces the halant forms of consonants in Indic scripts. For example, in Sanskrit (Devanagari script), syllable final consonants are frequently required in their halant form.
Equivalent OpenType tag: 'haln'
Respaces glyphs designed to be set on full-em widths, fitting them onto half-em widths. This differs from hwid in that it does not substitute new glyphs.
Equivalent OpenType tag: 'halt'
Replaces the default (current) forms with the historical alternates. While some ligatures are also used for historical effect, this feature deals only with single characters. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hist'
Replaces standard kana with forms that have been specially designed for only horizontal writing. This is a typographic optimization for improved fit and more even color.
Equivalent OpenType tag: 'hkna'
Replaces the default (current) forms with the historical alternates. Some ligatures were in common use in the past, but appear anachronistic today. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hlig'
Replaces glyphs on proportional widths, or fixed widths other than half an em, with glyphs on half-em (en) widths. Many CJKV fonts have glyphs which are set on multiple widths; this feature selects the half-em version. There are various contexts in which this is the preferred behavior, including compatibility with older desktop documents.
Equivalent OpenType tag: 'hwid'
Used to access the JIS X 0212-1990 glyphs for the cases when the JIS X 0213:2004 form is encoded. The JIS X 0212-1990 (aka, "Hojo Kanji") and JIS X 0213:2004 character sets overlap significantly. In some cases their prototypical glyphs differ. When building fonts that support both JIS X 0212-1990 and JIS X 0213:2004 (such as those supporting the Adobe-Japan 1-6 character collection), it is recommended that JIS X 0213:2004 forms be the preferred encoded form.
Equivalent OpenType tag: 'hojo'
The National Language Council (NLC) of Japan has defined new glyph shapes for a number of JIS characters, which were incorporated into JIS X 0213:2004 as new prototypical forms. The 'jp04' feature is A subset of the 'nlck' feature, and is used to access these prototypical glyphs in a manner that maintains the integrity of JIS X 0213:2004.
Equivalent OpenType tag: 'jp04'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS C 6226-1978 (JIS78) specification.
Equivalent OpenType tag: 'jp78'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS X 0208-1983 (JIS83) specification.
Equivalent OpenType tag: 'jp83'
Replaces Japanese glyphs from the JIS78 or JIS83 specifications with the corresponding forms from the JIS X 0208-1990 (JIS90) specification.
Equivalent OpenType tag: 'jp90'
Adjusts amount of space between glyphs, generally to provide optically consistent spacing between glyphs. Although a well-designed typeface has consistent inter-glyph spacing overall, some glyph combinations require adjustment for improved legibility. Besides standard adjustment in the horizontal direction, this feature can supply size-dependent kerning data via device tables, "cross-stream" kerning in the Y text direction, and adjustment of glyph placement independent of the advance adjustment. Note that this feature may apply to runs of more than two glyphs, and would not be used in monospaced fonts. Also note that this feature does not apply to text set vertically.
Equivalent OpenType tag: 'kern'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers the ligatures which the designer/manufacturer judges should be used in normal conditions.
Equivalent OpenType tag: 'liga'
Changes selected figures from oldstyle to the default lining form. For example, a user may invoke this feature in order to get lining figures, which fit better with all-capital text. This feature overrides results of the Oldstyle Figures feature (onum).
Equivalent OpenType tag: 'lnum'
Enables localized forms of glyphs to be substituted for default forms. Many scripts used to write multiple languages over wide geographical areas have developed localized variant forms of specific letters, which are used by individual literary communities. For example, a number of letters in the Bulgarian and Serbian alphabets have forms distinct from their Russian counterparts and from each other. In some cases the localized form differs only subtly from the script 'norm', in others the forms are radically distinct.
Equivalent OpenType tag: 'locl'
Positions mark glyphs with respect to base glyphs. For example, in Arabic script positioning the Hamza above the Yeh.
Equivalent OpenType tag: 'mark'
Replaces standard typographic forms of Greek glyphs with corresponding forms commonly used in mathematical notation (which are a subset of the Greek alphabet).
Equivalent OpenType tag: 'mgrk'
Positions marks with respect to other marks. Required in various non-Latin scripts like Arabic. For example, in Arabic, the ligaturised mark Ha with Hamza above it can also be obtained by positioning these marks relative to one another.
Equivalent OpenType tag: 'mkmk'
Replaces default glyphs with various notational forms (such as glyphs placed in open or solid circles, squares, parentheses, diamonds or rounded boxes). In some cases an annotation form may already be present, but the user may want a different one.
Equivalent OpenType tag: 'nalt'
Used to access glyphs made from glyph shapes defined by the National Language Council (NLC) of Japan for a number of JIS characters in 2000.
Equivalent OpenType tag: 'nlck'
Changes selected figures from the default lining style to oldstyle form. For example, a user may invoke this feature to get oldstyle figures, which fit better into the flow of normal upper- and lowercase text. This feature overrides results of the Lining Figures feature (lnum).
Equivalent OpenType tag: 'onum'
Replaces default alphabetic glyphs with the corresponding ordinal forms for use after figures. One exception to the follows-a-figure rule is the numero character (U+2116), which is actually a ligature substitution, but is best accessed through this feature.
Equivalent OpenType tag: 'ordn'
Respaces glyphs designed to be set on full-em widths, fitting them onto individual (more or less proportional) horizontal widths. This differs from pwid in that it does not substitute new glyphs (GPOS, not GSUB feature). The user may prefer the monospaced form, or may simply want to ensure that the glyph is well-fit and not rotated in vertical setting (Latin forms designed for proportional spacing would be rotated).
Equivalent OpenType tag: 'palt'
Turns lowercase characters into petite capitals. Forms related to petite capitals, such as specially designed figures, may be included. Some fonts contain an additional size of capital letters, shorter than the regular smallcaps and it is referred to as petite caps. Such forms are most likely to be found in designs with a small lowercase x-height, where they better harmonise with lowercase text than the taller smallcaps (for examples of petite caps, see the Emigre type families Mrs Eaves and Filosofia).
Equivalent OpenType tag: 'pcap'
Replaces figure glyphs set on uniform (tabular) widths with corresponding glyphs set on glyph-specific (proportional) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'pnum'
Replaces glyphs set on uniform widths (typically full or half-em) with proportionally spaced glyphs. The proportional variants are often used for the Latin characters in CJKV fonts, but may also be used for Kana in Japanese fonts.
Equivalent OpenType tag: 'pwid'
Replaces glyphs on other widths with glyphs set on widths of one quarter of an em (half an en). The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'qwid'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures, which the script determines as required to be used in normal conditions. This feature is important for some scripts to ensure correct glyph formation.
Equivalent OpenType tag: 'rlig'
Identifies glyphs in the font which have been designed for "ruby", from the old typesetting term for four-point-sized type. Japanese typesetting often uses smaller kana glyphs, generally in superscripted form, to clarify the meaning of kanji which may be unfamiliar to the reader.
Equivalent OpenType tag: 'ruby'
Replaces the default forms with the stylistic alternates. Many fonts contain alternate glyph designs for a purely esthetic effect; these don't always fit into a clear category like swash or historical. As in the case of swash glyphs, there may be more than one alternate form.
Equivalent OpenType tag: 'salt'
Replaces lining or oldstyle figures with inferior figures (smaller glyphs which sit lower than the standard baseline, primarily for chemical or mathematical notation). May also replace lowercase characters with alphabetic inferiors.
Equivalent OpenType tag: 'sinf'
Turns lowercase characters into small capitals. This corresponds to the common SC font layout. It is generally used for display lines set in Large & small caps, such as titles. Forms related to small capitals, such as oldstyle figures, may be included.
Equivalent OpenType tag: 'smcp'
Replaces 'traditional' Chinese or Japanese forms with the corresponding 'simplified' forms.
Equivalent OpenType tag: 'smpl'
In addition to, or instead of, stylistic alternatives of individual glyphs (see 'salt' feature), some fonts may contain sets of stylistic variant glyphs corresponding to portions of the character set, such as multiple variants for lowercase letters in a Latin font. Glyphs in stylistic sets may be designed to harmonise visually, interract in particular ways, or otherwise work together. Examples of fonts including stylistic sets are Zapfino Linotype and Adobe's Poetica. Individual features numbered sequentially with the tag name convention 'ss01' 'ss02' 'ss03' . 'ss20' provide a mechanism for glyphs in these sets to be associated via GSUB lookup indexes to default forms and to each other, and for users to select from available stylistic sets
Equivalent OpenType tag: 'ss01'
See the description for
Equivalent OpenType tag: 'ss02'
See the description for
Equivalent OpenType tag: 'ss03'
See the description for
Equivalent OpenType tag: 'ss04'
See the description for
Equivalent OpenType tag: 'ss05'
See the description for
Equivalent OpenType tag: 'ss06'
See the description for
Equivalent OpenType tag: 'ss07'
See the description for
Equivalent OpenType tag: 'ss08'
See the description for
Equivalent OpenType tag: 'ss09'
See the description for
Equivalent OpenType tag: 'ss10'
See the description for
Equivalent OpenType tag: 'ss11'
See the description for
Equivalent OpenType tag: 'ss12'
See the description for
Equivalent OpenType tag: 'ss13'
See the description for
Equivalent OpenType tag: 'ss14'
See the description for
Equivalent OpenType tag: 'ss15'
See the description for
Equivalent OpenType tag: 'ss16'
See the description for
Equivalent OpenType tag: 'ss17'
See the description for
Equivalent OpenType tag: 'ss18'
See the description for
Equivalent OpenType tag: 'ss19'
See the description for
Equivalent OpenType tag: 'ss20'
May replace a default glyph with a subscript glyph, or it may combine a glyph substitution with positioning adjustments for proper placement.
Equivalent OpenType tag: 'subs'
Replaces lining or oldstyle figures with superior figures (primarily for footnote indication), and replaces lowercase letters with superior letters (primarily for abbreviated French titles).
Equivalent OpenType tag: 'sups'
Replaces default character glyphs with corresponding swash glyphs. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'swsh'
Replaces the default glyphs with corresponding forms designed specifically for titling. These may be all-capital and/or larger on the body, and adjusted for viewing at larger sizes.
Equivalent OpenType tag: 'titl'
Replaces 'simplified' Japanese kanji forms with the corresponding 'traditional' forms. This is equivalent to the Traditional Forms feature, but explicitly limited to the traditional forms considered proper for use in personal names (as many as 205 glyphs in some fonts).
Equivalent OpenType tag: 'tnam'
Replaces figure glyphs set on proportional widths with corresponding glyphs set on uniform (tabular) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'tnum'
Replaces 'simplified' Chinese hanzi or Japanese kanji forms with the corresponding 'traditional' forms.
Equivalent OpenType tag: 'trad'
Replaces glyphs on other widths with glyphs set on widths of one third of an em. The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'twid'
Maps upper- and lowercase letters to a mixed set of lowercase and small capital forms, resulting in a single case alphabet (for an example of unicase, see the Emigre type family Filosofia). The letters substituted may vary from font to font, as appropriate to the design. If aligning to the x-height, smallcap glyphs may be substituted, or specially designed unicase forms might be used. Substitutions might also include specially designed figures. -
Equivalent OpenType tag: 'unic'
Allows the user to change from the default 0 to a slashed form. Some fonts contain both a default form of zero, and an alternative form which uses a diagonal slash through the counter. Especially in condensed designs, it can be difficult to distinguish between 0 and O (zero and capital O) in any situation where capitals and lining figures may be arbitrarily mixed.
Equivalent OpenType tag: 'zero'
The type of a font represented by a single font file. Font formats that consist of multiple files, for example Type 1 .PFM and .PFB, have separate enum values for each of the file types.
-Font type is not recognized by the DirectWrite font system.
OpenType font with CFF outlines.
OpenType font with TrueType outlines.
OpenType font that contains a TrueType collection.
Type 1 PFM font.
Type 1 PFB font.
Vector .FON font.
Bitmap .FON font.
Specifies algorithmic style simulations to be applied to the font face. Bold and oblique simulations can be combined via bitwise OR operation.
-Style simulations are not recommended for good typographic quality.
-Indicates that no simulations are applied to the font face.
Indicates that algorithmic emboldening is applied to the font face.
Indicates that algorithmic italicization is applied to the font face.
Represents the degree to which a font has been stretched compared to a font's normal aspect ratio. The enumerated values correspond to the usWidthClass definition in the OpenType specification. The usWidthClass represents an integer value between 1 and 9?lower values indicate narrower widths; higher values indicate wider widths.
-A font stretch describes the degree to which a font form is stretched from its normal aspect ratio, which is the original width to height ratio specified for the glyphs in the font. - The following illustration shows an example of Normal and Condensed stretches for the Rockwell Bold typeface.
Note??Values other than the ones defined in the enumeration are considered to be invalid, and are rejected by font API functions.
-Predefined font stretch : Not known (0).
Predefined font stretch : Ultra-condensed (1).
Predefined font stretch : Extra-condensed (2).
Predefined font stretch : Condensed (3).
Predefined font stretch : Semi-condensed (4).
Predefined font stretch : Normal (5).
Predefined font stretch : Medium (5).
Predefined font stretch : Semi-expanded (6).
Predefined font stretch : Expanded (7).
Predefined font stretch : Extra-expanded (8).
Predefined font stretch : Ultra-expanded (9).
Represents the style of a font face as normal, italic, or oblique.
-Three terms categorize the slant of a font: normal, italic, and oblique.
| Font style | Description |
|---|---|
| Normal | The characters in a normal, or roman, font are upright. - |
| Italic - | The characters in an italic font are truly slanted and appear as they were designed. - |
| Oblique | The characters in an oblique font are artificially slanted. |
?
For Oblique, the slant is achieved by performing a shear transformation on the characters from a normal font. When a true italic font is not available on a computer or printer, an oblique style can be generated from the normal font and used to simulate an italic font. The following illustration shows the normal, italic, and oblique font styles for the Palatino Linotype font. Notice how the italic font style has a more flowing and visually appealing appearance than the oblique font style, which is simply created by skewing the normal font style version of the text.
Note?? Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
-Font style : Normal.
Font style : Oblique.
Font style : Italic.
Represents the density of a typeface, in terms of the lightness or heaviness of the strokes. The enumerated values correspond to the usWeightClass definition in the OpenType specification. The usWeightClass represents an integer value between 1 and 999. Lower values indicate lighter weights; higher values indicate heavier weights.
-Weight differences are generally differentiated by an increased stroke or thickness that is associated with a given character in a typeface, as compared to a "normal" character from that same typeface. - The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
Note??Not all weights are available for all typefaces. When a weight is not available for a typeface, the closest matching weight is returned.
Font weight values less than 1 or greater than 999 are considered invalid, and they are rejected by font API functions.
-Predefined font weight : Thin (100).
Predefined font weight : Extra-light (200).
Predefined font weight : Ultra-light (200).
Predefined font weight : Light (300).
Predefined font weight : Normal (400).
Predefined font weight : Regular (400).
Predefined font weight : Medium (500).
Predefined font weight : Demi-bold (600).
Predefined font weight : Semi-bold (600).
Predefined font weight : Bold (700).
Predefined font weight : Extra-bold (800).
Predefined font weight : Ultra-bold (800).
Predefined font weight : Black (900).
Predefined font weight : Heavy (900).
Predefined font weight : Extra-black (950).
Predefined font weight : Ultra-black (950).
The
The text analyzer outputs
Glyph orientation is upright.
Glyph orientation is rotated 90 degrees clockwise.
Glyph orientation is upside-down.
Glyph orientation is rotated 270 degrees clockwise.
The informational string enumeration which identifies a string embedded in a font file.
-Indicates the string containing the unspecified name ID.
Indicates the string containing the copyright notice provided by the font.
Indicates the string containing a version number.
Indicates the string containing the trademark information provided by the font.
Indicates the string containing the name of the font manufacturer.
Indicates the string containing the name of the font designer.
Indicates the string containing the URL of the font designer (with protocol, e.g., http://, ftp://).
Indicates the string containing the description of the font. This may also contain revision information, usage recommendations, history, features, etc.
Indicates the string containing the URL of the font vendor (with protocol, e.g., http://, ftp://). If a unique serial number is embedded in the URL, it can be used to register the font.
Indicates the string containing the description of how the font may be legally used, or different example scenarios for licensed use.
Indicates the string containing the URL where additional licensing information can be found.
Indicates the string containing the GDI-compatible family name. Since GDI allows a maximum of four fonts per family, fonts in the same family may have different GDI-compatible family names (e.g., "Arial", "Arial Narrow", "Arial Black").
Indicates the string containing a GDI-compatible subfamily name.
Indicates the string containing the family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI. This name is typically only present if it differs from the GDI-compatible family name.
Indicates the string containing the subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
Contains sample text for display in font lists. This can be the font name or any other text that the designer thinks is the best example to display the font in.
The method used for line spacing in a text layout.
-The line spacing method is set by using the SetLineSpacing method of the
Line spacing depends solely on the content, adjusting to accommodate the size of fonts and inline objects.
Lines are explicitly set to uniform spacing, regardless of the size of fonts and inline objects. This can be useful to avoid the uneven appearance that can occur from font fallback.
Specifies how to apply number substitution on digits and related punctuation.
-Specifies that the substitution method should be determined based on the LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
If the culture is Arabic or Persian, specifies that the number shapes depend on the context. Either traditional or nominal number shapes are used, depending on the nearest preceding strong character or (if there is none) the reading direction of the paragraph.
Specifies that code points 0x30-0x39 are always rendered as nominal numeral shapes (ones of the European number), that is, no substitution is performed.
Specifies that numbers are rendered using the national number shapes as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
Specifies that numbers are rendered using the traditional shapes for the specified culture. For most cultures, this is the same as NativeNational. However, NativeNational results in Latin numbers for some Arabic cultures, whereasDWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL results in arabic numbers for all Arabic cultures.
The
Glyphs are rendered in outline mode by default at large sizes for performance reasons, but how large (that is, the outline threshold) depends on the quality of outline rendering. If the graphics system renders anti-aliased outlines, a relatively low threshold is used. But if the graphics system renders aliased outlines, a much higher threshold is used.
-The
Any arm style.
No fit arm style.
The arm style is straight horizontal.
The arm style is straight wedge.
The arm style is straight vertical.
The arm style is straight single serif.
The arm style is straight double serif.
The arm style is non-straight horizontal.
The arm style is non-straight wedge.
The arm style is non-straight vertical.
The arm style is non-straight single serif.
The arm style is non-straight double serif.
The arm style is straight horizontal.
The arm style is straight vertical.
The arm style is non-straight horizontal.
The arm style is non-straight wedge.
The arm style is non-straight vertical.
The arm style is non-straight single serif.
The arm style is non-straight double serif.
The
Any aspect ratio.
No fit for aspect ratio.
Very condensed aspect ratio.
Condensed aspect ratio.
Normal aspect ratio.
Expanded aspect ratio.
Very expanded aspect ratio.
The
Any aspect ratio.
No fit for aspect ratio.
Very condensed aspect ratio.
Condensed aspect ratio.
Normal aspect ratio.
Expanded aspect ratio.
Very expanded aspect ratio.
The
Any range.
No fit for range.
The range includes extended collection.
The range includes literals.
The range doesn't include lower case.
The range includes small capitals.
The
Any contrast.
No fit contrast.
No contrast.
Very low contrast.
Low contrast.
Medium low contrast.
Medium contrast.
Medium high contrast.
High contrast.
Very high contrast.
Horizontal low contrast.
Horizontal medium contrast.
Horizontal high contrast.
Broken contrast.
The
Any class of decorative typeface.
No fit for decorative typeface.
Derivative decorative typeface.
Nonstandard topology decorative typeface.
Nonstandard elements decorative typeface.
Nonstandard aspect decorative typeface.
Initials decorative typeface.
TBD
TBD
TBD
TBD
TBD
TBD
The
Any decorative topology.
No fit for decorative topology.
Standard decorative topology.
Square decorative topology.
Multiple segment decorative topology.
Art deco decorative topology.
Uneven weighting decorative topology.
Diverse arms decorative topology.
Diverse forms decorative topology.
Lombardic forms decorative topology.
Upper case in lower case decorative topology.
The decorative topology is implied.
Horseshoe E and A decorative topology.
Cursive decorative topology.
Blackletter decorative topology.
Swash variance decorative topology.
The
Any typeface classification.
No fit typeface classification.
Text display typeface classification.
Script (or hand written) typeface classification.
Decorative typeface classification.
Symbol typeface classification.
Pictorial (or symbol) typeface classification.
The
Any fill.
No fit for fill.
The fill is the standard solid fill.
No fill.
The fill is patterned fill.
The fill is complex fill.
The fill is shaped fill.
The fill is drawn distressed.
The
Any finials.
No fit for finials.
No loops.
No closed loops.
No open loops.
Sharp with no loops.
Sharp with closed loops.
Sharp with open loops.
Tapered with no loops.
Tapered with closed loops.
Tapered with open loops.
Round with no loops.
Round with closed loops.
Round with open loops.
The
Any letterform.
No fit letterform.
Normal contact letterform.
Normal weighted letterform.
Normal boxed letterform.
Normal flattened letterform.
Normal rounded letterform.
Normal off-center letterform.
Normal square letterform.
Oblique contact letterform.
Oblique weighted letterform.
Oblique boxed letterform.
Oblique flattened letterform.
Oblique rounded letterform.
Oblique off-center letterform.
Oblique square letterform.
The
Any lining.
No fit for lining.
No lining.
The lining is inline.
The lining is outline.
The lining is engraved.
The lining is shadowed.
The lining is relief.
The lining is backdrop.
The
Any midline.
No fit midline.
Standard trimmed midline.
Standard pointed midline.
Standard serifed midline.
High trimmed midline.
High pointed midline.
High serifed midline.
Constant trimmed midline.
Constant pointed midline.
Constant serifed midline.
Low trimmed midline.
Low pointed midline.
Low serifed midline.
The
Any proportion for the text.
No fit proportion for the text.
Old style proportion for the text.
Modern proportion for the text.
Extra width proportion for the text.
Expanded proportion for the text.
Condensed proportion for the text.
Very expanded proportion for the text.
Very condensed proportion for the text.
Monospaced proportion for the text.
The
Any script form.
No fit for script form.
Script form is upright with no wrapping.
Script form is upright with some wrapping.
Script form is upright with more wrapping.
Script form is upright with extreme wrapping.
Script form is oblique with no wrapping.
Script form is oblique with some wrapping.
Script form is oblique with more wrapping.
Script form is oblique with extreme wrapping.
Script form is exaggerated with no wrapping.
Script form is exaggerated with some wrapping.
Script form is exaggerated with more wrapping.
Script form is exaggerated with extreme wrapping.
The
Any script topology.
No fit for script topology.
Script topology is roman disconnected.
Script topology is roman trailing.
Script topology is roman connected.
Script topology is cursive disconnected.
Script topology is cursive trailing.
Script topology is cursive connected.
Script topology is black-letter disconnected.
Script topology is black-letter trailing.
Script topology is black-letter connected.
The
Any appearance of the serif text.
No fit appearance of the serif text.
Cove appearance of the serif text.
Obtuse cove appearance of the serif text.
Square cove appearance of the serif text.
Obtuse square cove appearance of the serif text.
Square appearance of the serif text.
Thin appearance of the serif text.
Oval appearance of the serif text.
Exaggerated appearance of the serif text.
Triangle appearance of the serif text.
Normal sans appearance of the serif text.
Obtuse sans appearance of the serif text.
Perpendicular sans appearance of the serif text.
Flared appearance of the serif text.
Rounded appearance of the serif text.
Script appearance of the serif text.
Perpendicular sans appearance of the serif text.
Oval appearance of the serif text.
The
Any spacing.
No fit for spacing.
Spacing is proportional.
Spacing is monospace.
The
Any stroke variation for text characters.
No fit stroke variation for text characters.
No stroke variation for text characters.
The stroke variation for text characters is gradual diagonal.
The stroke variation for text characters is gradual transitional.
The stroke variation for text characters is gradual vertical.
The stroke variation for text characters is gradual horizontal.
The stroke variation for text characters is rapid vertical.
The stroke variation for text characters is rapid horizontal.
The stroke variation for text characters is instant vertical.
The stroke variation for text characters is instant horizontal.
The
Any aspect ratio of symbolic characters.
No fit for aspect ratio of symbolic characters.
No width aspect ratio of symbolic characters.
Exceptionally wide symbolic characters.
Super wide symbolic characters.
Very wide symbolic characters.
Wide symbolic characters.
Normal aspect ratio of symbolic characters.
Narrow symbolic characters.
Very narrow symbolic characters.
The
Any kind of symbol set.
No fit for the kind of symbol set.
The kind of symbol set is montages.
The kind of symbol set is pictures.
The kind of symbol set is shapes.
The kind of symbol set is scientific symbols.
The kind of symbol set is music symbols.
The kind of symbol set is expert symbols.
The kind of symbol set is patterns.
The kind of symbol set is boarders.
The kind of symbol set is icons.
The kind of symbol set is logos.
The kind of symbol set is industry specific.
The
Any kind of tool.
No fit for the kind of tool.
Flat NIB tool.
Pressure point tool.
Engraved tool.
Ball tool.
Brush tool.
Rough tool.
Felt-pen-brush-tip tool.
Wild-brush tool.
The
The
Any weight.
No fit weight.
Very light weight.
Light weight.
Thin weight.
Book weight.
Medium weight.
Demi weight.
Bold weight.
Heavy weight.
Black weight.
Extra black weight.
Extra black weight.
The
Any xascent.
No fit for xascent.
Very low xascent.
Low xascent.
Medium xascent.
High xascent.
Very high xascent.
The
Any xheight.
No fit xheight.
Constant small xheight.
Constant standard xheight.
Constant large xheight.
Ducking small xheight.
Ducking standard xheight.
Ducking large xheight.
Constant standard xheight.
Ducking standard xheight.
Specifies the alignment of paragraph text along the flow direction axis, relative to the top and bottom of the flow's layout box.
-The top of the text flow is aligned to the top edge of the layout box.
The bottom of the text flow is aligned to the bottom edge of the layout box.
The center of the flow is aligned to the center of the layout box.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text. -
-The red, green, and blue color components of each pixel are assumed to occupy the same point.
Each pixel is composed of three vertical stripes, with red on the left, green in the center, and blue on the right. This is the most common pixel geometry for LCD monitors.
Each pixel is composed of three vertical stripes, with blue on the left, green in the center, and red on the right.
Specifies the direction in which reading progresses.
-Indicates that reading progresses from left to right.
Indicates that reading progresses from right to left.
Represents a method of rendering glyphs.
-Specifies that the rendering mode is determined automatically, based on the font and size.
Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground color of the text or retains the color of the background.
Specifies ClearType rendering with the same metrics as bi-level text. Glyphs can only be positioned on whole-pixel boundaries.
Specifies ClearType rendering with the same metrics as text rendering using GDI using a font created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than with bi-level text, but glyphs are still positioned on whole-pixel boundaries.
Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is typically used with small to medium font sizes (up to 16 ppem).
Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions. This is typically used at larger sizes to makes curves and diagonal lines look smoother, at the expense of some softness.
Specifies that rendering should bypass the rasterizer and use the outlines directly. This is typically used at very large sizes.
Indicates additional shaping requirements for text.
-Indicates that there is no additional shaping requirements for text. Text is shaped with the writing system default behavior.
Indicates that text should leave no visible control or format control characters.
Specifies the alignment of paragraph text along the reading direction axis, relative to the leading and trailing edge of the layout box.
-The leading edge of the paragraph text is aligned to the leading edge of the layout box.
The trailing edge of the paragraph text is aligned to the trailing edge of the layout box.
The center of the paragraph text is aligned to the center of the layout box.
The
ClearType antialiasing computes coverage independently for the red, green, and blue color elements of each pixel. This allows for more detail than conventional antialiasing. However, because there is no one alpha value for each pixel, ClearType is not suitable for rendering text onto a transparent intermediate bitmap.
Grayscale antialiasing computes one coverage value for each pixel. Because the alpha value of each pixel is well-defined, text can be rendered onto a transparent bitmap, which can then be composited with other content.
Note??Grayscale rendering with
Identifies a type of alpha texture.
-An alpha texture is a bitmap of alpha values, each representing opacity of a pixel or subpixel.
-Specifies an alpha texture for aliased text rendering (that is, each pixel is either fully opaque or fully transparent), with one byte per pixel.
Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and one byte per pixel in the vertical dimension.
Specifies the text granularity used to trim text overflowing the layout box.
-No trimming occurs. Text flows beyond the layout width.
Trimming occurs at a character cluster boundary.
Trimming occurs at a word boundary.
The
The client specifies a
Note??This is the client preference, and the constraints of the script determine the final presentation.
-The default glyph orientation. In vertical layout, naturally horizontal scripts (Latin, Thai, Arabic, Devanagari) rotate 90 degrees clockwise, while ideographic scripts (Chinese, Japanese, Korean) remain upright, 0 degrees.
Stacked glyph orientation. Ideographic scripts and scripts that permit stacking (Latin, Hebrew) are stacked in vertical reading layout. Connected scripts (Arabic, Syriac, 'Phags-pa, Ogham), which would otherwise look broken if glyphs were kept at 0 degrees, remain connected and rotate.
Specifies the word wrapping to be used in a particular multiline paragraph.
-Indicates that words are broken across lines to avoid text overflowing the layout box.
Indicates that words are kept within the same line even when it overflows the layout box. This option is often used with scrolling to reveal overflow text.
Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
-A value that specifies whether the factory object will be shared or isolated.
A
An address of a reference to the newly created DirectWrite factory object.
If this function succeeds, it returns
This function creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects. DirectWrite factory contains internal state data such as font loader registration and cached font data. In most cases it is recommended you use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state data, and thereby reduce memory usage. However, there are cases when it is desirable to reduce the impact of a component, such as a plug-in from an untrusted source, on the rest of the process, by sandboxing and isolating it from the rest of the process components. In such cases, it is recommended you use an isolated factory for the sandboxed component.
The following example shows how to create a shared DirectWrite factory.
if (SUCCEEDED(hr))
- { hr = Encapsulates a 32-bit device independent bitmap and device context, which you can use for rendering glyphs.
-Gets the current text antialiasing mode of the bitmap render target.
-Returns a
Sets the current text antialiasing mode of the bitmap render target.
-A
Returns
The antialiasing mode of a newly-created bitmap render target defaults to
Gets or sets the current text antialiasing mode of the bitmap render target.
-Creates a rendering parameters object with the specified properties.
-Creates a rendering parameters object with the specified properties.
-The gamma level to be set for the new rendering parameters object.
The enhanced contrast level to be set for the new rendering parameters object.
The amount of contrast enhancement to use for grayscale antialiasing, zero or greater.
The ClearType level to be set for the new rendering parameters object.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.
A value that represents the method (for example, ClearType natural quality) for rendering glyphs.
When this method returns, contains an address of a reference to the newly created rendering parameters object.
Standard
Represents a physical font in a font collection. This interface is used to create font faces from physical fonts, or to retrieve information such as font face metrics or face names from existing font faces.
-Gets the font family to which the specified font belongs.
-When this method returns, contains an address of a reference to the font family object to which the specified font belongs.
If this method succeeds, it returns
Gets the weight, or stroke thickness, of the specified font.
-A value that indicates the weight for the specified font.
Gets the stretch, or width, of the specified font.
-A value that indicates the type of stretch, or width, applied to the specified font.
Gets the style, or slope, of the specified font.
-A value that indicates the type of style, or slope, of the specified font.
Determines whether the font is a symbol font.
-TRUE if the font is a symbol font; otherwise,
Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-When this method returns, contains an address to a reference to the newly created localized strings object.
If this method succeeds, it returns
Gets a localized strings collection containing the specified informational strings, indexed by locale name.
-A value that identifies the informational string to get. For example,
When this method returns, contains an address of a reference to the newly created localized strings object.
When this method returns, TRUE if the font contains the specified string ID; otherwise,
If the font does not contain the string specified by informationalStringID, the return value is
Gets a value that indicates what simulations are applied to the specified font.
-A value that indicates one or more of the types of simulations (none, bold, or oblique) applied to the specified font.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-When this method returns, contains a structure that has font metrics for the current font face. The metrics returned by this function are in font design units.
Determines whether the font supports a specified character.
-A Unicode (UCS-4) character value for the method to inspect.
When this method returns, TRUE if the font supports the specified character; otherwise,
Creates a font face object for the font.
-When this method returns, contains an address of a reference to the newly created font face object.
If this method succeeds, it returns
Gets the font family to which the specified font belongs.
-Gets the weight, or stroke thickness, of the specified font.
-Gets the stretch, or width, of the specified font.
-Gets the style, or slope, of the specified font.
-Determines whether the font is a symbol font.
-Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
-Gets a value that indicates what simulations are applied to the specified font.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Represents a physical font in a font collection.
-Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
- A filled
Gets the PANOSE values from the font and is used for font selection and matching.
-A reference to the
If the font has no PANOSE values, they are set to 'any' (0) and DirectWrite doesn't simulate those values.
-Retrieves the list of character ranges supported by a font.
-The maximum number of character ranges passed in from the client.
An array of
A reference to the actual number of character ranges, regardless of the maximum count.
This method can return one of these values.
| Return value | Description |
|---|---|
| | The method executed successfully. |
| The buffer is too small. The actualRangeCount was more than the maxRangeCount. |
?
The list of character ranges supported by a font, is useful for scenarios like character picking, glyph display, and efficient font selection lookup. GetUnicodeRanges is similar to GDI's GetFontUnicodeRanges, except that it returns the full Unicode range, not just 16-bit UCS-2.
These ranges are from the cmap, not the OS/2::ulCodePageRange1.
If this method is unavailable, you can use the
The
Determines if the font is monospaced, that is, the characters are the same fixed-pitch width (non-proportional).
-Returns true if the font is monospaced, else it returns false.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Gets the PANOSE values from the font and is used for font selection and matching.
-If the font has no PANOSE values, they are set to 'any' (0) and DirectWrite doesn't simulate those values.
-Determines if the font is monospaced, that is, the characters are the same fixed-pitch width (non-proportional).
-Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
-This method should be used to determine the actual rendering mode in cases where the rendering mode of the rendering params object is
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-A filled
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
-The logical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
A reference to a
Standard
Gets caret metrics for the font in design units.
-A reference to the
Caret metrics are used by text editors for drawing the correct caret placement and slant.
-Retrieves a list of character ranges supported by a font.
-Maximum number of character ranges passed in from the client.
An array of
A reference to the actual number of character ranges, regardless of the maximum count.
This method can return one of these values.
| Return value | Description |
|---|---|
| | The method executed successfully. |
| The buffer is too small. The actualRangeCount was more than the maxRangeCount. |
?
A list of character ranges supported by the font is useful for scenarios like character picking, glyph display, and efficient font selection lookup. This is similar to GDI's GetFontUnicodeRanges, except that it returns the full Unicode range, not just 16-bit UCS-2.
These ranges are from the cmap, not the OS/2::ulCodePageRange1.
If this method is unavailable, you can use the
The
Determines whether the font of a text range is monospaced, that is, the font characters are the same fixed-pitch width.
-Returns TRUE if the font is monospaced, otherwise it returns
Retrieves the advances in design units for a sequences of glyphs.
-The number of glyphs to retrieve advances for.
An array of glyph id's to retrieve advances for.
The returned advances in font design units for each glyph.
Retrieve the glyph's vertical advance height rather than horizontal advance widths.
If this method succeeds, it returns
This is equivalent to calling GetGlyphMetrics and using only the advance width and height.
-Returns the pixel-aligned advances for a sequences of glyphs.
-Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
When
Retrieve the glyph's vertical advances rather than horizontal advances.
Total glyphs to retrieve adjustments for.
An array of glyph id's to retrieve advances.
The returned advances in font design units for each glyph.
If this method succeeds, it returns
This is equivalent to calling GetGdiCompatibleGlyphMetrics and using only the advance width and height.
Like GetGdiCompatibleGlyphMetrics, these are in design units, meaning they must be scaled down by DWRITE_FONT_METRICS::designUnitsPerEm.
-Retrieves the kerning pair adjustments from the font's kern table.
-Number of glyphs to retrieve adjustments for.
An array of glyph id's to retrieve adjustments for.
The advances, returned in font design units, for each glyph. The last glyph adjustment is zero.
If this method succeeds, it returns
GetKerningPairAdjustments isn't a direct replacement for GDI's character based GetKerningPairs, but it serves the same role, without the client needing to cache them locally. GetKerningPairAdjustments also uses glyph id's directly rather than UCS-2 characters (how the kern table actually stores them), which avoids glyph collapse and ambiguity, such as the dash and hyphen, or space and non-breaking space.
Newer fonts may have only GPOS kerning instead of the legacy pair-table kerning. Such fonts, like Gabriola, will only return 0's for adjustments. GetKerningPairAdjustments doesn't virtualize and flatten these GPOS entries into kerning pairs.
You can realize a performance benefit by calling IDWriteFontFace1::HasKerningPairs to determine whether you need to call GetKerningPairAdjustments. If you previously called IDWriteFontFace1::HasKerningPairs and it returned
Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
-The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
The number of physical pixels per DIP in a horizontal position. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
The number of physical pixels per DIP in a vertical position. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
Specifies the world transform.
Whether the glyphs in the run are sideways or not.
A
The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:
When this method returns, contains a value that indicates the recommended rendering mode to use.
If this method succeeds, it returns
This method should be used to determine the actual rendering mode in cases where the rendering mode of the rendering params object is
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
-Gets caret metrics for the font in design units.
-Caret metrics are used by text editors for drawing the correct caret placement and slant.
-Determines whether the font of a text range is monospaced, that is, the font characters are the same fixed-pitch width.
-Represents a family of related fonts.
-A font family is a set of fonts that share the same family name, such as "Times New Roman", but that differ in features. These feature differences include style, such as italic, and weight, such as bold. The following illustration shows examples of fonts that are members of the "Times New Roman" font family.
An
null ; // Get the font family.
- if (SUCCEEDED(hr))
- { hr = pFontCollection->GetFontFamily(i, &pFontFamily);
- }
- The font family name is used to specify the font family for text layout and text format objects. You can get a list of localized font family names from an
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- }
- Represents a list of fonts.
-Gets the font collection that contains the fonts in the font list.
-When this method returns, contains the address of a reference to the current
If this method succeeds, it returns
Gets the number of fonts in the font list.
-The number of fonts in the font list.
Gets a font given its zero-based index.
-Zero-based index of the font in the font list.
When this method returns, contains the address of a reference to the newly created
Gets the font collection that contains the fonts in the font list.
-Gets the number of fonts in the font list.
-Creates a localized strings object that contains the family names for the font family, indexed by locale name.
-The address of a reference to the newly created
If this method succeeds, it returns
The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- Gets the font that best matches the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
When this method returns, contains the address of a reference to the newly created
Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
-A value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
An address of a reference to the newly created
Creates a localized strings object that contains the family names for the font family, indexed by locale name.
- The following code example shows how to get the font family name from a
null ; // Get a list of localized strings for the family name.
- if (SUCCEEDED(hr))
- { hr = pFontFamily->GetFamilyNames(&pFamilyNames);
- } UINT32 index = 0;
- null )
- { hr = E_OUTOFMEMORY;
- } // Get the family name.
- if (SUCCEEDED(hr))
- { hr = pFamilyNames->GetString(index, name, length+1);
- }
- A built-in implementation of the
Obtains the length of the absolute file path from the font file reference key.
-Font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
Size of font file reference key in bytes.
Length of the file path string, not including the terminated
Obtains the absolute font file path from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The character array that receives the local file path.
The length of the file path character array.
If this method succeeds, it returns
Obtains the last write time of the file from the font file reference key.
-The font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The time of the last font file modification.
Represents text rendering settings for glyph rasterization and filtering.
-Gets the amount of contrast enhancement to use for grayscale antialiasing.
-The contrast enhancement value. Valid values are greater than or equal to zero.
Gets the amount of contrast enhancement to use for grayscale antialiasing.
-Sets the spacing between characters.
-Enables or disables pair-kerning on a given text range.
-The flag that indicates whether text is pair-kerned.
The text range to which the change applies.
If this method succeeds, it returns
Gets whether or not pair-kerning is enabled at given position.
-The current text position.
The flag that indicates whether text is pair-kerned.
The position range of the current format.
If this method succeeds, it returns
Sets the spacing between characters.
-The spacing before each character, in reading order.
The spacing after each character, in reading order.
The minimum advance of each character, to prevent characters from becoming too thin or zero-width. This must be zero or greater.
Text range to which this change applies.
If this method succeeds, it returns
Gets the spacing between characters.
-The current text position.
The spacing before each character, in reading order.
The spacing after each character, in reading order.
The minimum advance of each character, to prevent characters from becoming too thin or zero-width. This must be zero or greater.
The position range of the current format.
If this method succeeds, it returns
The
Vertical rise of the caret. Rise / Run yields the caret angle. Rise = 1 for perfectly upright fonts (non-italic).
Horizontal run of the caret. Rise / Run yields the caret angle. Run = 0 for perfectly upright fonts (non-italic).
Horizontal offset of the caret along the baseline for good appearance. Offset = 0 for perfectly upright fonts (non-italic).
Contains information about a glyph cluster.
-The total advance width of all glyphs in the cluster.
The number of text positions in the cluster.
Indicates whether a line can be broken right after the cluster.
Indicates whether the cluster corresponds to a whitespace character.
Indicates whether the cluster corresponds to a newline character.
Indicates whether the cluster corresponds to a soft hyphen character.
Indicates whether the cluster is read from right to left.
Reserved for future use.
The
The number of font design units per em unit. Font files use their own coordinate system of font design units. A font design unit is the smallest measurable unit in the em square, an imaginary square that is used to size and align glyphs. The concept of em square is used as a reference scale factor when defining font size and device transformation semantics. The size of one em square is also commonly used to compute the paragraph identation value.
The ascent value of the font face in font design units. Ascent is the distance from the top of font character alignment box to the English baseline.
The descent value of the font face in font design units. Descent is the distance from the bottom of font character alignment box to the English baseline.
The line gap in font design units. Recommended additional white space to add between lines to improve legibility. The recommended line spacing (baseline-to-baseline distance) is the sum of ascent, descent, and lineGap. The line gap is usually positive or zero but can be negative, in which case the recommended line spacing is less than the height of the character alignment box.
The cap height value of the font face in font design units. Cap height is the distance from the English baseline to the top of a typical English capital. Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
The x-height value of the font face in font design units. x-height is the distance from the English baseline to the top of lowercase letter "x", or a similar lowercase character.
The underline position value of the font face in font design units. Underline position is the position of underline relative to the English baseline. The value is usually made negative in order to place the underline below the baseline.
The suggested underline thickness value of the font face in font design units.
The strikethrough position value of the font face in font design units. Strikethrough position is the position of strikethrough relative to the English baseline. The value is usually made positive in order to place the strikethrough above the baseline.
The suggested strikethrough thickness value of the font face in font design units.
The
The number of font design units per em unit. Font files use their own coordinate system of font design units. A font design unit is the smallest measurable unit in the em square, an imaginary square that is used to size and align glyphs. The concept of em square is used as a reference scale factor when defining font size and device transformation semantics. The size of one em square is also commonly used to compute the paragraph identation value.
The ascent value of the font face in font design units. Ascent is the distance from the top of font character alignment box to the English baseline.
The descent value of the font face in font design units. Descent is the distance from the bottom of font character alignment box to the English baseline.
The line gap in font design units. Recommended additional white space to add between lines to improve legibility. The recommended line spacing (baseline-to-baseline distance) is the sum of ascent, descent, and lineGap. The line gap is usually positive or zero but can be negative, in which case the recommended line spacing is less than the height of the character alignment box.
The cap height value of the font face in font design units. Cap height is the distance from the English baseline to the top of a typical English capital. Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
The x-height value of the font face in font design units. x-height is the distance from the English baseline to the top of lowercase letter "x", or a similar lowercase character.
The underline position value of the font face in font design units. Underline position is the position of underline relative to the English baseline. The value is usually made negative in order to place the underline below the baseline.
The suggested underline thickness value of the font face in font design units.
The strikethrough position value of the font face in font design units. Strikethrough position is the position of strikethrough relative to the English baseline. The value is usually made positive in order to place the strikethrough above the baseline.
The suggested strikethrough thickness value of the font face in font design units.
Specifies the metrics of an individual glyph. The units depend on how the metrics are obtained.
-Specifies the X offset from the glyph origin to the left edge of the black box. The glyph origin is the current horizontal writing position. A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally. The value is negative when the right edge of the black box overhangs the layout box.
Specifies the vertical offset from the vertical origin to the top of the black box. Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically. Note that the term "origin" by itself denotes the horizontal origin. The vertical origin is different. Its Y coordinate is specified by verticalOriginY value, and its X coordinate is half the advanceWidth to the right of the horizontal origin.
Specifies the vertical distance from the bottom edge of the black box to the advance height. This is positive when the bottom edge of the black box is within the layout box, or negative when the bottom edge of black box overhangs the layout box.
Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system. The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing and the top (that is, yMax) of the glyph's bounding box.
The optional adjustment to a glyph's position.
-An glyph offset changes the position of a glyph without affecting the pen position. Offsets are in logical, pre-transform units.
-The offset in the advance direction of the run. A positive advance offset moves the glyph to the right (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
The offset in the ascent direction, that is, the direction ascenders point. A positive ascender offset moves the glyph up (in pre-transform coordinates). A negative ascender offset moves the glyph down.
Describes the region obtained by a hit test.
-The first text position within the hit region.
The number of text positions within the hit region.
The x-coordinate of the upper-left corner of the hit region.
The y-coordinate of the upper-left corner of the hit region.
The width of the hit region.
The height of the hit region.
The BIDI level of the text positions within the hit region.
true if the hit region contains text; otherwise, false.
Contains properties describing the geometric measurement of an - application-defined inline object.
-The width of the inline object.
The height of the inline object.
The distance from the top of the object to the point where it is lined up with the adjacent text. If the baseline is at the bottom, then baseline simply equals height.
A Boolean flag that indicates whether the object is to be placed upright or alongside the text baseline for vertical text.
Justifies an array of glyph advances to fit the line width.
-You call JustifyGlyphAdvances after you call
The line width.
The glyph count.
A reference to a
An array of glyph advances.
An array of glyph offsets.
The returned array of justified glyph advances.
The returned array of justified glyph offsets.
Contains information about a formatted line of text.
-The number of text positions in the text line. This includes any trailing whitespace and newline characters.
The number of whitespace positions at the end of the text line. Newline sequences are considered whitespace.
The number of characters in the newline sequence at the end of the text line. If the count is zero, then the text line was either wrapped or it is the end of the text.
The height of the text line.
The distance from the top of the text line to its baseline.
The line is trimmed.
Indicates how much any visible DIPs (device independent pixels) overshoot each side of the layout or inline objects.
Positive overhangs indicate that the visible area extends outside the layout box or inline object, while negative values mean there is whitespace inside. The returned values are unaffected by rendering transforms or pixel snapping. Additionally, they may not exactly match the final target's pixel bounds after applying grid fitting and hinting.
-The distance from the left-most visible DIP to its left-alignment edge.
The distance from the top-most visible DIP to its top alignment edge.
The distance from the right-most visible DIP to its right-alignment edge.
The distance from the bottom-most visible DIP to its lower-alignment edge.
The
No fit for range.
The range includes extended collection.
The range includes literals.
The range doesn't include lower case.
The range includes small capitals.
Any range.
Stores the association of text and its writing system script, as well as some display attributes.
-The zero-based index representation of writing system script.
A value that indicates additional shaping requirement of text.
Retrieves the properties for a given script.
-The script for a run of text returned from
A reference to a
Shaping output properties for an output glyph.
-Indicates that the glyph is shaped alone.
Reserved for future use.
Contains information regarding the size and placement of strikethroughs. All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the strikethrough, measured parallel to the baseline.
A value that indicates the thickness of the strikethrough, measured perpendicular to the baseline.
A value that indicates the offset of the strikethrough from the baseline. A positive offset represents a position below the baseline and a negative offset is above. Typically, the offset will be negative.
Reading direction of the text associated with the strikethrough. This value is used to interpret whether the width value runs horizontally or vertically.
Flow direction of the text associated with the strikethrough. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters containing the locale of the text that is the strikethrough is being drawn over.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Contains the metrics associated with text after layout. All coordinates are in device independent pixels (DIPs).
-A value that indicates the left-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the top-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the width of the formatted text, while ignoring trailing whitespace at the end of each line.
The width of the formatted text, taking into account the trailing whitespace at the end of each line.
The height of the formatted text. The height of an empty string is set to the same value as that of the default font.
The initial width given to the layout. It can be either larger or smaller than the text content width, depending on whether the text was wrapped.
Initial height given to the layout. Depending on the length of the text, it may be larger or smaller than the text content height.
The maximum reordering count of any line of text, used to calculate the most number of hit-testing boxes needed. If the layout has no bidirectional text, or no text at all, the minimum level is 1.
Specifies the trimming option for text overflowing the layout box.
-A value that specifies the text granularity used to trim text overflowing the layout box.
A character code used as the delimiter that signals the beginning of the portion of text to be preserved. Most useful for path ellipsis, where the delimiter would be a slash.
A value that indicates how many occurrences of the delimiter to step back.
Contains a set of typographic features to be applied during text shaping.
-A reference to a structure that specifies properties used to identify and execute typographic features in the font.
A value that indicates the number of features being applied to a font face.
Contains information about the width, thickness, offset, run height, reading direction, and flow direction of an underline.
-All coordinates are in device independent pixels (DIPs).
-A value that indicates the width of the underline, measured parallel to the baseline.
A value that indicates the thickness of the underline, measured perpendicular to the baseline.
A value that indicates the offset of the underline from the baseline. A positive offset represents a position below the baseline (away from the text) and a negative offset is above (toward the text).
A value that indicates the height of the tallest run where the underline is applied.
A value that indicates the reading direction of the text associated with the underline. This value is used to interpret whether the width value runs horizontally or vertically.
A value that indicates the flow direction of the text associated with the underline. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters which contains the locale of the text that the underline is being drawn under. For example, in vertical text, the underline belongs on the left for Chinese but on the right for Japanese.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Retrieves the list of character ranges supported by a font.
-The list of character ranges supported by a font, is useful for scenarios like character picking, glyph display, and efficient font selection lookup. GetUnicodeRanges is similar to GDI's GetFontUnicodeRanges, except that it returns the full Unicode range, not just 16-bit UCS-2.
These ranges are from the cmap, not the OS/2::ulCodePageRange1.
If this method is unavailable, you can use the
The
The maximum number of character ranges passed in from the client.
An array of
[This documentation is preliminary and is subject to change.]
The 2D affine transform effect applies a spatial transform to a image based on a 3X2 matrix using the Direct2D matrix transform and any of six interpolation modes. You can use this effect to rotate, scale, skew, or translate an image. Or, you can combine these operations. Affine transfers preserve parallel lines and the ratio of distances between any three points in an image.
The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
The 2D affine transform effect applies a spatial transform to a image based on a 3X2 matrix using the Direct2D matrix transform and any of six interpolation modes. You can use this effect to rotate, scale, skew, or translate an image. Or, you can combine these operations. Affine transfers preserve parallel lines and the ratio of distances between any three points in an image.
The CLSID for this effect is
Specifies how the alpha value of a bitmap or render target should be treated.
-The
When describing an RGBA color using straight alpha, the alpha value of the color is stored in the alpha channel. For example, to describe a red color that is 60% opaque, you'd use the following values: (255, 0, 0, 255 * 0.6) = (255, 0, 0, 153). The 255 value indicates full red, and 153 (which is 60 percent of 255) indicates that the color should have an opacity of 60 percent.
When describing an RGBA color using premultiplied alpha, each color is multiplied by the alpha value: (255 * 0.6, 0 * 0.6, 0 * 0.6, 255 * 0.6) = (153, 0, 0, 153).
Regardless of the alpha mode of the render target, D2D1_COLOR_F values are always interpreted as straight alpha. For example, when specifying the color of an
Regardless of the alpha mode setting, a render target's contents support transparency. For example, if you draw a partially transparent red rectangle with a render target with an alpha mode of
If you draw a partially transparent red rectangle when the alpha mode is
If you specify an alpha mode other than
You can use the SetTextAntialiasMode method to change the text antialias mode back to
The alpha value might not be meaningful.
The alpha value has been premultiplied. Each color is first scaled by the alpha value. The alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. If a color channel value in a premultiplied format is greater than the alpha channel, the standard source-over blending math results in an additive blend.
The alpha value has not been premultiplied. The alpha channel indicates the transparency of the color.
The alpha value is ignored.
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Specifies whether an arc should be greater than 180 degrees.
-An arc's sweep should be 180 degrees or less.
An arc's sweep should be 180 degrees or greater.
[This documentation is preliminary and is subject to change.]
You can use the Direct2D Effects API to process images using GPU accelerated effects and develop your own effects. It also provides interoperation with other parts of Direct2D, DirectWrite, Windows Imaging Component (WIC) and Direct3D.
This topic contains:
Specifies the algorithm that is used when images are scaled or rotated.
- To stretch an image, each pixel in the original image must be mapped to a group of pixels in the larger image. To shrink an image, groups of pixels in the original image must be mapped to single pixels in the smaller image. The effectiveness of the algorithms that perform these mappings determines the quality of a scaled image. Algorithms that produce higher-quality scaled images tend to require more processing time.
Use the exact color of the nearest bitmap pixel to the current rendering pixel.
Interpolate a color from the four bitmap pixels that are the nearest to the rendering pixel.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Used to represent the bit depth of the imaging pipeline in Direct2D.
-If
If
If
The bitmap is created with default properties.
The bitmap can be used as a device context target.
The bitmap cannot be used as an input.
The bitmap can be read from from the CPU.
The bitmap works with ID2D1GdiInteropRenderTarget::GetDC.
[This documentation is preliminary and is subject to change.]
Shows how to use the Windows::Storage::FileOpenPicker to load an image into Direct2D Effects. If you want to let the user select an image file from storage in a Metro style app, we recommend that you use the FileOpenPicker.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies how one of the color sources is to be derived and optionally specifies a preblend operation on the color source.
-This enumeration has the same numeric values as D3D10_BLEND.
-The data source is black (0, 0, 0, 0). There is no preblend operation.
The data source is white (1, 1, 1, 1). There is no preblend operation.
The data source is color data (RGB) from the second input of the blend transform. There is a preblend operation.
The data source is color data (RGB) from second input of the blend transform. The preblend operation inverts the data, generating 1 - RGB.
The data source is alpha data (A) from second input of the blend transform. There is no preblend operation.
The data source is alpha data (A) from the second input of the blend transform. The preblend operation inverts the data, generating 1 - A.
The data source is alpha data (A) from the first input of the blend transform. There is no preblend operation.
The data source is alpha data (A) from the first input of the blend transform. The preblend operation inverts the data, generating 1 - A.
The data source is color data from the first input of the blend transform. There is no preblend operation.
The data source is color data from the first input of the blend transform. The preblend operation inverts the data, generating 1 - RGB.
The data source is alpha data from the second input of the blend transform. The preblend operation clamps the data to 1 or less.
The data source is the blend factor. There is no preblend operation.
The data source is the blend factor. The preblend operation inverts the blend factor, generating 1 - blend_factor.
[This documentation is preliminary and is subject to change.]
Use the blend effect to combine 2 images. This effect has 26 blend modes. These modes are useful for overlapping images that have transparency.
The CLSID for this effect is The CLSID for this effect is
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
[This documentation is preliminary and is subject to change.]
Use the blend effect to combine 2 images. This effect has 26 blend modes. These modes are useful for overlapping images that have transparency.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the 3D transform effect to apply an arbitrary 4x4 transform matrix to an image.
This effect applies the matrix (Mt) you provide to the corner vertices of the source image ([ x y z 1 ]) using this calculation:
[ xr yr zr 1 ]=[ x y z 1 ]*Mt
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents the bit depth of the imaging pipeline in Direct2D.
-The buffer precision is not specified.
Use 8-bit normalized integer per channel.
Use 16-bit floats per channel.
Use 16-bit normalized integer per channel.
Use 32-bit floats per channel.
Describes the shape at the end of a line or segment.
-The following illustration shows the available cap styles for lines or segments. The red portion of the line shows the extra area added by the line cap setting.
-A cap that does not extend past the last point of the line. Comparable to cap used for objects other than lines.
Half of a square that has a length equal to the line thickness.
A semicircle that has a diameter equal to the line thickness.
An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line.
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
[This documentation is preliminary and is subject to change.]
Use the displacement map effect to displace the pixels of the input image by the intensity values of a second input image.
The CLSID for this effect is The CLSID for this effect is
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
[This documentation is preliminary and is subject to change.]
Use the color management effect to transform an image from one ICC (International Color Consortium color profile to another. The effect transforms the image according to the ICC specification.
The CLSID for this effect is
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Specifies the different methods by which two geometries can be combined.
-The following illustration shows the different geometry combine modes. -
-The two regions are combined by taking the union of both. Given two geometries, A and B, the resulting geometry is geometry A + geometry B.
The two regions are combined by taking their intersection. The new area consists of the overlapping region between the two geometries.
The two regions are combined by taking the area that exists in the first region but not the second and the area that exists in the second region but not the first. Given two geometries, A and B, the new region consists of (A-B) + (B-A).
The second region is excluded from the first. Given two geometries, A and B, the area of geometry B is removed from the area of geometry A, producing a region that is A-B.
Specifies additional features supportable by a compatible render target when it is created. This enumeration allows a bitwise combination of its member values.
-Use this enumeration when creating a compatible render target with the CreateCompatibleRenderTarget method. For more information about compatible render targets, see the Render Targets Overview.
The
The render target supports no additional features.
The render target supports interoperability with the Windows Graphics Device Interface (GDI).
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Used to specify the blend mode for all of the Direct2D blending operations.
-The composite mode is the default for the type of object.
The standard source-over-destination blend mode.
The destination is rendered over the source.
Performs a logical clip of the source pixels against the destination pixels.
Performs a logical clip of the destination pixels against the source pixels.
This is the logical inverse to source in.
The is the logical inverse to destination in.
Writes the source pixels over the destination where there are destination pixels.
Writes the destination pixels over the source where there are destination pixels.
The source is inverted with the destination.
The channel components are summed.
The source is copied to the destination; the destination pixels are ignored.
The destination is copied over the source pixels.
[This documentation is preliminary and is subject to change.]
Use the composite effect to combine 2 or more images. This effect has 13 different composite modes. The composite modes are as subset of those that are defined by the Scalable Vector Graphics (SVG) filter effects.
The composite effect accepts 2 or more inputs. When you specify 2 images, destination is the first input (index 0) and the source is the second input (index 1). If you specify more than 2 inputs the images are composited starting with the first input and the second and so on.
This effect implements all of the modes using the blending unit of the graphics processing unit (GPU).
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the convolve matrix effect to apply an arbitrary 2D kernel to an image. You can use this effect to blur, detect edges, emboss, or sharpen an image.
The CLSID for this effect is The CLSID for this effect is
Describes the sequence of dashes and gaps in a stroke.
-The following illustration shows several available dash styles. For more information, see the Stroke Style Example.
-A solid line with no breaks.
A dash followed by a gap of equal length. The dash and the gap are each twice as long as the stroke thickness.
The equivalent dash array for
A dot followed by a longer gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap, followed by another dot, followed by another gap.
The equivalent dash array for
The dash pattern is specified by an array of floating-point values.
Indicates the type of information provided by the Direct2D Debug Layer.
-To receive debugging messages, you must install the Direct2D Debug Layer.
-Specifies how a device context is initialized for GDI rendering when it is retrieved from the render target.
-Use this enumeration with the ID2D1GdiInteropRenderTarget::GetDC method to specify how the device context is initialized for GDI rendering.
-The current contents of the render target are copied to the device context when it is initialized.
The device context is cleared to transparent black when it is initialized.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines options that should be applied to a device context.
-The device context is created with default options.
Distribute rendering work across multiple threads.
[This documentation is preliminary and is subject to change.]
The directional blur effect is similar to Gaussian blur, except you can skew the blur in a particular direction. You can use this effect to make an image look as if it is in motion or to emphasize an animated image.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the discrete transfer effect to map the color intensities of an image using a step transfer function created from a list of values you provide.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the displacement map effect to displace the pixels of the input image by the intensity values of a second input image.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the distant-diffuse lighting effect to create an image that appears to be a reflective surface with where the light source appears to be coming from a long distance (like the sun or overhead lights) and the light is reflecting in all directions. This effect uses the alpha channel as a height map and lights the image with a distant light source. The color of the output bitmap is a result of light color, light position, and the surface geometry of the image.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the distant-diffuse lighting effect to create an image that appears to be a reflective surface with where the light source appears to be coming from a long distance (like the sun or overhead lights) and the light is reflecting in all directions. This effect uses the alpha channel as a height map and lights the image with a distant light source. The color of the output bitmap is a result of light color, light position, and the surface geometry of the image.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the distant-specular lighting effect to create an image that appears to be a reflective surface where the light source appears to be coming from a long distance (like the sun or overhead lights). This effect uses the alpha channel as a height map and lights the image with a distant light source. The color of the output bitmap is a result of light color, light position, and the surface geometry.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the distant-specular lighting effect to create an image that appears to be a reflective surface where the light source appears to be coming from a long distance (like the sun or overhead lights). This effect uses the alpha channel as a height map and lights the image with a distant light source. The color of the output bitmap is a result of light color, light position, and the surface geometry.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the DPI compensation effect to automatically adjust an input bitmap to match the DPI of the context. This is useful for situations where a bitmap is created or loaded at a different DPI than the screen.
The CLSID for this effect is
Specifies whether text snapping is suppressed or clipping to the layout rectangle is enabled. This enumeration allows a bitwise combination of its member values.
-Text is not vertically snapped to pixel boundaries. This setting is recommended for text that is being animated.
Text is clipped to the layout rectangle.
Text is vertically snapped to pixel boundaries and is not clipped to the layout rectangle.
Specifies how a brush paints areas outside of its normal content area.
-For an
For an example, see the Draw Extend Mode Example.
-Repeat the edge pixels of the brush's content for all regions outside the normal content area.
Repeat the brush's content.
The same as
Specifies whether Direct2D provides synchronization for an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread, and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note the qualifier "On the CPU": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU; however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
-Applies to: desktop apps | Metro style apps
Describes the minimum DirectX support required for hardware rendering by a render target.
-Direct2D determines whether the video card provides adequate hardware rendering support.
The video card must support DirectX 9.
Describes the minimum DirectX support required for hardware rendering by a render target.
-Direct2D determines whether the video card provides adequate hardware rendering support.
The video card must support DirectX 9.
The video card must support DirectX 10.
Indicates whether a specific
Indicates whether a specific
Specifies how the intersecting areas of geometries or figures are combined to form the area of the composite geometry.
-Use the
Direct2D fills the interior of a path by using one of the two fill modes specified by this enumeration:
To see the difference between the winding and alternate fill modes, assume that you have four circles with the same center and a different radius, as shown in the following illustration. The first one has the radius of 25, the second 50, the third 75, and the fourth 100.
The following illustration shows the shape filled by using the alternate fill mode. Notice that the center and third ring are not filled. This is because a ray drawn from any point in either of those two rings passes through an even number of segments.
The following illustration explains this process.
The following illustration shows how the same shape is filled when the winding fill mode is specified.
Notice that all the rings are filled. This is because all the segments run in the same direction, so a ray drawn from any point will cross one or more segments, and the sum of the crossings will not equal zero.
The following illustration explains this process. The red arrows represent the direction in which the segments are drawn and the black arrow represents an arbitrary ray that runs from a point in the innermost ring. Starting with a value of zero, for each segment that the ray crosses, a value of one is added for every clockwise intersection. All points lie in the fill region in this illustration, because the count does not equal zero.
-Determines whether a point is in the fill region by drawing a ray from that point to infinity in any direction, and then counting the number of path segments within the given shape that the ray crosses. If this number is odd, the point is in the fill region; if even, the point is outside the fill region.
Determines whether a point is in the fill region of the path by drawing a ray from that point to infinity in any direction, and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left, as long as left and right are seen from the perspective of the ray. After counting the crossings, if the result is zero, then the point is outside the path. Otherwise, it is inside the path.
Applies to: desktop apps | Metro style apps
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
Specifies which gamma is used for interpolation.
-Interpolating in a linear gamma space (
The first gradient is interpolated linearly in the space of the render target (sRGB in this case), and one can see the dark bands between each color. The second gradient uses a gamma-correct linear interpolation, and thus does not exhibit the same variations in brightness.
-Interpolation is performed in the standard RGB (sRGB) gamma.
Interpolation is performed in the linear-gamma color space.
[This documentation is preliminary and is subject to change.]
Use the gamma transfer effect to map the color intensities of an image using a gamma function created using an amplitude, exponent, and offset you provide for each channel.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the Gaussian blur effect to create a blur based on the Gaussian function over the entire input image.
You can use this effect to create glows and drop shadows and use the composite effect to apply the result to the original image. It is useful in photo processing for filters like highlights and shadows. You can use the output of this effect for input into lighting effects, like the Specular Lighting or Diffuse Lighting effects, because the alpha channel is blurred, too and lighting effects use the alpha channel to determine surface geometry as a height map.
This effect is used by the built-in Shadow effect.
The CLSID for this effect is The CLSID for this effect is
Describes how one geometry object is spatially related to another geometry object.
-The relationship between the two geometries cannot be determined. This value is never returned by any D2D method.
The two geometries do not intersect at all.
The instance geometry is entirely contained by the passed-in geometry.
The instance geometry entirely contains the passed-in geometry.
The two geometries overlap but neither completely contains the other.
Specifies how a geometry is simplified to an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies the interpolation mode of a bitmap in DrawImage.
-Specifies options that can be applied when a layer resource is applied to create a layer.
-ClearType antialiasing must use the current contents of the render target to blend properly. When a pushed layer requests initializing for ClearType, Direct 2D copies the current contents of the render target into the layer so that ClearType antialiasing can be performed. Rendering ClearType text into a transparent layer does not produce the desired results.
A small performance hit from re-copying content occurs when
The text in this layer does not use ClearType antialiasing.
The layer renders correctly for ClearType text. If the render target is set to ClearType, the layer continues to render ClearType. If the render target is set to ClearType and this option is not specified, the render target will be set to render gray-scale until the layer is popped. The caller can override this default by calling SetTextAntialiasMode while within the layer. This flag is slightly slower than the default.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Returns a
[This documentation is preliminary and is subject to change.]
Use the linear transfer effect to map the color intensities of an image using a linear function created a list of values you provide for each channel.
The CLSID for this effect is The CLSID for this effect is
Describes the shape that joins two lines or segments.
- A miter limit affects how sharp miter joins are allowed to be. If the line join style is
The following illustration shows different line join settings for the same stroked path geometry. For more information, see Stroke Style Example.
-Regular angular vertices.
Beveled vertices.
Rounded vertices.
Regular angular vertices unless the join would extend beyond the miter limit; otherwise, beveled vertices.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies how the memory to be mapped from the corresponding
The
These flags will be not be able to be used on bitmaps created by the
Indicates the measuring method used for text layout.
-Specifies that text is measured using glyph ideal metrics whose values are independent to the current display resolution.
Specifies that text is measured using glyph display-compatible metrics whose values tuned for the current display resolution.
Specifies that text is measured using the same glyph display metrics as text measured by GDI using a font created with CLEARTYPE_NATURAL_QUALITY.
Describes whether an opacity mask contains graphics or text. Direct2D uses this information to determine which gamma space to use when blending the opacity mask.
-The opacity mask contains graphics. The opacity mask is blended in the gamma 2.2 color space.
The opacity mask contains non-GDI text. The gamma space used for blending is obtained from the render target's text rendering parameters. (
The opacity mask contains text rendered using the GDI-compatible rendering mode. The opacity mask is blended using the gamma for GDI rendering.
Indicates whether a segment should be stroked and whether the join between this segment and the previous one should be smooth. This enumeration allows a bitwise combination of its member values.
-The segment is joined as specified by the
The segment is not stroked.
The segment is always joined with the one preceding it using a round line join, regardless of which
Applies to: desktop apps | Metro style apps
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
[This documentation is preliminary and is subject to change.]
Use the point-diffuse lighting effect to create an image that appears to be a reflective surface with light reflecting in all directions. This effect uses the alpha channel as a height map and lights the image with a point light source. The color of the output bitmap is a result of light color, light position, and the surface geometry of the image.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the point-specular lighting effect to create an image that appears to be a reflective surface. The effect uses the alpha channel of the image as a height map and a point light source that you position, and calculates the reflection and light according to the specular portion of the Phong lighting model.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the point-specular lighting effect to create an image that appears to be a reflective surface. The effect uses the alpha channel of the image as a height map and a point light source that you position, and calculates the reflection and light according to the specular portion of the Phong lighting model.
The CLSID for this effect is The CLSID for this effect is
Describes how a render target behaves when it presents its content. This enumeration allows a bitwise combination of its member values.
-The render target waits until the display refreshes to present and discards the frame upon presenting.
The render target does not discard the frame upon presenting.
The render target does not wait until the display refreshes to present.
Applies to: desktop apps | Metro style apps
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Applies to: desktop apps | Metro style apps
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
Describes whether a render target uses hardware or software rendering, or if Direct2D should select the rendering mode.
-Not every render target supports hardware rendering. For more information, see the Render Targets Overview.
-The render target uses hardware rendering, if available; otherwise, it uses software rendering.
The render target uses software rendering only.
The render target uses hardware rendering only.
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
[This documentation is preliminary and is subject to change.]
Use this effect to scale an image up or down. The effect has six scaling modes: nearest neighbor, linear, cubic, multi-sample linear, anisotropic, and high quality cubic.
The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use this effect to scale an image up or down. The effect has six scaling modes: nearest neighbor, linear, cubic, multi-sample linear, anisotropic, and high quality cubic.
The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the spot-diffuse lighting effect to create an image that appears to be a reflective surface with where the light source is limited to a directed cone of light and the light is reflecting in all directions. This effect uses the alpha channel as a height map and lights the image with a spot light source. The color of the output bitmap is a result of light color, light position, and the surface geometry.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the spot-diffuse lighting effect to create an image that appears to be a reflective surface with where the light source is limited to a directed cone of light and the light is reflecting in all directions. This effect uses the alpha channel as a height map and lights the image with a spot light source. The color of the output bitmap is a result of light color, light position, and the surface geometry.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the spot-specular lighting effect to create an image that appears to be a reflective surface where the light source is limited to a directed cone of light. This effect uses the alpha channel as a height map and lights the image with a point light source. The color of the output bitmap is a result of light color, light position, the direction of the cone and the surface geometry according to the specular portion of the Phong lighting model.
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
sDefines how the world transform, dots per inch (dpi), and stroke width affect the shape of the pen used to stroke a primitive.
-It is important to distinguish between the geometry being stroked and the shape of the stroke pen. When
The stroke respects the currently set world transform, the dpi, and the stroke width.
The stroke does not respect the world transform but it does respect the dpi and stroke width.
The stroke is forced to 1 pixel wide (in device space) and does not respect the world transform, the dpi, or the stroke width.
Applies to: desktop apps | Metro style apps
Specifies how the edges of nontext primitives are rendered.
-Edges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Defines the direction that an elliptical arc is drawn.
-Arcs are drawn in a counterclockwise (negative-angle) direction.
Arcs are drawn in a clockwise (positive-angle) direction.
[This documentation is preliminary and is subject to change.]
Use the table transfer effect to map the color intensities of an image using a transfer function created from interpolating a list of values you provide.
The CLSID for this effect is The CLSID for this effect is
Describes the antialiasing mode used for drawing text.
-This enumeration is used with the SetTextAntialiasMode of an
By default, Direct2D renders text in ClearType mode. Factors that can downgrade the default quality to grayscale or aliased:
Use the system default. See Remarks.
Use ClearType antialiasing.
Use grayscale antialiasing.
Do not use antialiasing.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Specifies whether rental-threaded or multi-threaded objects should be created by Direct2D.
-The created objects can be used in a rental-threaded manner.
The created objects will be free threaded.
[This documentation is preliminary and is subject to change.]
Use the 3D transform effect to apply an arbitrary 4x4 transform matrix to an image.
This effect applies the matrix (Mt) you provide to the corner vertices of the source image ([ x y z 1 ]) using this calculation:
[ xr yr zr 1 ]=[ x y z 1 ]*Mt
The CLSID for this effect is The CLSID for this effect is
[This documentation is preliminary and is subject to change.]
Use the 3D transform effect to apply an arbitrary 4x4 transform matrix to an image.
This effect applies the matrix (Mt) you provide to the corner vertices of the source image ([ x y z 1 ]) using this calculation:
[ xr yr zr 1 ]=[ x y z 1 ]*Mt
The CLSID for this effect is The CLSID for this effect is
Applies to: desktop apps | Metro style apps
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
-The render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes flags that influence how the renderer interacts with a custom vertex shader.
-The logical equivalent of having no flags set.
If this flag is set, the renderer assumes that the vertex shader will cover the entire region of interest with vertices and need not clear the destination render target. If this flag is not set, the renderer assumes that the vertices do not cover the entire region interest and must clear the render target to transparent black first.
The renderer will use a depth buffer when rendering custom vertices. The depth buffer will be used for calculating occlusion information. This can result in the renderer output being draw-order dependent if it contains transparency.
Indicates that custom vertices do not overlap each other.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines the properties of a vertex buffer that are standard for all vertex shader definitions.
-If usage is dynamic, the system might return a system memory buffer and copy these vertices into the rendering vertex buffer for each element.
If the initialization data is not specified, the buffer will be uninitialized.
-The number of inputs to the vertex shader.
Indicates how frequently the vertex buffer is likely to be updated.
Describes whether a window is occluded.
-If the window was occluded the last time EndDraw was called, the next time the render target calls CheckWindowState, it returns
The window is not occluded.
The window is occluded.
Tries to invert the specified matrix.
-The matrix to invert.
true if the matrix was inverted; otherwise, false.
Indicates whether the specified matrix is invertible.
-The matrix to test.
true if the matrix was inverted; otherwise, false.
Creates a rotation transformation that rotates by the specified angle about the specified point.
-The clockwise rotation angle, in degrees.
The point about which to rotate.
When this method returns, contains the new rotation transformation. You must allocate storage for this parameter.
Rotation occurs in the plane of the 2-D surface.
-Creates a factory object that can be used to create Direct2D resources.
-The threading model of the factory and the resources it creates.
A reference to the IID of
The level of detail provided to the debugging layer.
When this method returns, contains the address to a reference to the new factory.
If this function succeeds, it returns
The
Creates a skew transformation that has the specified x-axis angle, y-axis angle, and center point.
-The x-axis skew angle, which is measured in degrees counterclockwise from the y-axis.
The y-axis skew angle, which is measured in degrees counterclockwise from the x-axis.
The center point of the skew operation.
When this method returns, contains the rotation transformation. You must allocate storate for this parameter.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a new Direct2D device associated with the provided DXGI device.
-The DXGI device the Direct2D device is associated with.
The properties to apply to the Direct2D device.
When this function returns, contains the address of a reference to a Direct2D device.
The function returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
This function will also create a new
If the creation properties are not specified, then d2dDevice will inherit its threading mode from dxgiDevice and debug tracing will not be enabled.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a new Direct2D device context associated with a DXGI surface.
-The DXGI surface the Direct2D device context is associated with.
The properties to apply to the Direct2D device context.
When this function returns, contains the address of a reference to a Direct2D device context.
The function returns an
| Description | |
|---|---|
| No error occurred. | |
| E_OUTOFMEMORY | Direct2D could not allocate sufficient memory to complete the call. |
| E_INVALIDARG | An invalid value was passed to the method. |
?
This function will also create a new
This function will also create a new
The DXGI device will be specified implicitly through dxgiSurface.
The created device context will have exactly the same behavior as if ID2D1DeviceContext::SetTargetSurface were called with the corresponding surface.
If creationProperties are not specified, the Direct2D device will inherit its threading mode from the DXGI device implied by dxgiSurface and debug tracing will not be enabled.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
TBD
TBD
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
TBD
-TBD
TBD
TBD
TBD
Issues drawing commands to a GDI device context.
-To create an
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
To enable the DC render target to work with GDI, set its pixel format to
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
When you use an
It's possible for GDI to apply a GDI transform (through the SetWorldTransform method) or other effect to the same DC used by the render target, in which case GDI transforms the bitmap produced by Direct2D. Using a GDI transform to transform the Direct2D content has the potential to degrade the visual quality of the output, because you're transforming a bitmap for which antialiasing and subpixel positioning have already been calculated.
For example, suppose you use the render target to draw a scene that contains antialiased geometries and text. If you use a GDI transform to apply a scale transform to the DC and scale the scene so that it's 10 times larger, you'll see pixelization and jagged edges. (If, however, you applied a similar transform using Direct2D, the visual quality of the scene would not be degraded.)
In some cases, it might not be obvious that GDI is performing additional processing that might degrade the quality of the Direct2D content. For example, on a right-to-left (RTL) build of Windows, content rendered by an
Depending on the type of content being rendered, you might want to prevent the inversion. If the Direct2D content includes ClearType text, this inversion will degrade the quality of the text.
You can control RTL rendering behavior by using the SetLayout GDI function. To prevent the mirroring, call the SetLayout GDI function and specify LAYOUT_BITMAPORIENTATIONPRESERVED as the only value for the second parameter (do not combine it with LAYOUT_RTL), as shown in the following example:
SetLayout(m_hwnd, LAYOUT_BITMAPORIENTATIONPRESERVED);Binds the render target to the device context to which it issues drawing commands.
-The device context to which the render target issues drawing commands.
The dimensions of the handle to a device context (
If this method succeeds, it returns
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
-Represents an ellipse.
-To create an elipse geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Gets the
Gets the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
A Direct2D resource that wraps a WMF, EMF, or EMF+ metafile.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
A Direct2D resource that wraps a WMF, EMF, or EMF+ metafile.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
A Direct2D resource that wraps a WMF, EMF, or EMF+ metafile.
-Direct2D provides the following interfaces.
-
Direct2D provides the following interfaces.
-
Represents a composite geometry, composed of other
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one.
CreatingTo create a
Direct2D geometries are immutable and device-independent resources created by
Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-A value that indicates how the intersecting areas of the geometries contained in this geometry group are combined.
Indicates the number of geometry objects in the geometry group.
-The number of geometries in the
Retrieves the geometries in the geometry group.
-When this method returns, contains the address of a reference to an array of geometries to be filled by this method. The length of the array is specified by the geometryCount parameter. If the array is
A value indicating the number of geometries to return in the geometries array. If this value is less than the number of geometries in the geometry group, the remaining geometries are omitted. If this value is larger than the number of geometries in the geometry group, the extra geometries are set to
The returned geometries are referenced and counted, and the caller must release them.
-Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
-Indicates the number of geometry objects in the geometry group.
-Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
-The
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
-Describes a geometric path that does not contain quadratic bezier curves or arcs.
-A geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Specifies the method used to determine which points are inside the geometry described by this geometry sink and which points are outside.
-The method used to determine whether a given point is part of the geometry.
The fill mode defaults to
Specifies stroke and join options to be applied to new segments added to the geometry sink.
-Stroke and join options to be applied to new segments added to the geometry sink.
After this method is called, the specified segment flags are applied to each segment subsequently added to the sink. The segment flags are applied to every additional segment until this method is called again and a different set of segment flags is specified.
-Starts a new figure at the specified point.
-The point at which to begin the new figure.
Whether the new figure should be hollow or filled.
If this method is called while a figure is currently in progress, the interface is invalidated and all future methods will fail.
-Creates a sequence of lines using the specified points and adds them to the geometry sink.
-A reference to an array of one or more points that describe the lines to draw. A line is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the first point in the array. if the array contains additional points, a line is drawn from the first point to the second point in the array, from the second point to the third point, and so on.
The number of points in the points array.
Creates a sequence of cubic Bezier curves and adds them to the geometry sink.
-A reference to an array of Bezier segments that describes the Bezier curves to create. A curve is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the end point of the first Bezier segment in the array. if the array contains additional Bezier segments, each subsequent Bezier segment uses the end point of the preceding Bezier segment as its start point.
The number of Bezier segments in the beziers array.
Ends the current figure; optionally, closes it.
-A value that indicates whether the current figure is closed. If the figure is closed, a line is drawn between the current point and the start point specified by BeginFigure.
Calling this method without a matching call to BeginFigure places the geometry sink in an error state; subsequent calls are ignored, and the overall failure will be returned when the Close method is called.
-Closes the geometry sink, indicates whether it is in an error state, and resets the sink's error state.
-If this method succeeds, it returns
Do not close the geometry sink while a figure is still in progress; doing so puts the geometry sink in an error state. For the close operation to be successful, there must be one EndFigure call for each call to BeginFigure.
After calling this method, the geometry sink might not be usable. Direct2D implementations of this interface do not allow the geometry sink to be modified after it is closed, but other implementations might not impose this restriction.
-Creates a line segment between the current point and the specified end point and adds it to the geometry sink.
-The end point of the line to draw.
Creates a cubic Bezier curve between the current point and the specified end point.
-A structure that describes the control points and end point of the Bezier curve to add.
Creates a quadratic Bezier curve between the current point and the specified endpoint.
-A structure that describes the control point and the endpoint of the quadratic Bezier curve to add.
Adds a sequence of quadratic Bezier segments as an array in a single call.
-An array of a sequence of quadratic Bezier segments.
A value indicating the number of quadratic Bezier segments in beziers.
Adds a single arc to the path geometry.
-The arc segment to add to the figure.
Represents the backing store required to render a layer.
-To create a layer, call the CreateLayer method of the render target where the layer will be used. To draw to a layer, push the layer to the render target stack by calling the PushLayer method. After you have finished drawing to the layer, call the PopLayer method.
Between PushLayer and PopLayer calls, the layer is in use and cannot be used by another render target.
If the size of the layer is not specified, the corresponding PushLayer call determines the minimum layer size, based on the layer content bounds and the geometric mask. The layer resource can be larger than the size required by PushLayer without any rendering artifacts.
If the size of a layer is specified, or if the layer has been used and the required backing store size as calculated during PushLayer is larger than the layer, then the layer resource is expanded on each axis monotonically to ensure that it is large enough. The layer resource never shrinks in size.
CreatingTo create a layer, call the CreateLayer method of the render target where the layer will be used.
A layer is a device-dependent resource: your application should create layers after it initializes the render target with which the layers will be used, and recreate the layers whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Gets the size of the layer in device-independent pixels.
-The size of the layer in device-independent pixels.
Gets the size of the layer in device-independent pixels.
-Paints an area with a linear gradient.
-An
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush start point and end point are also transformed.
It is possible to specify a gradient axis that does not completely fill the area that is being painted. When this occurs, the
To create a linear gradient brush, use the
A linear gradient brush is a device-dependent resource: your application should create linear gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Sets the starting coordinates of the linear gradient in the brush's coordinate space.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Sets the ending coordinates of the linear gradient in the brush's coordinate space.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the starting coordinates of the linear gradient.
-The starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves the ending coordinates of the linear gradient.
-The ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Retrieves or sets the starting coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
-Retrieves or sets the ending coordinates of the linear gradient.
-The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
- Retrieves the
Represents a set of vertices that form a list of triangles.
-To create a mesh, call the
A mesh is a device-dependent resource: your application should create meshes after it initializes the render target with which the meshes will be used, and recreate the meshes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Opens the mesh for population.
-When this method returns, contains a reference to a reference to an
If this method succeeds, it returns
Paints an area with a radial gradient.
-The
The brush maps the gradient stop position 0.0f of the gradient origin, and the position 1.0f is mapped to the ellipse boundary. When the gradient origin is within the ellipse, the contents of the ellipse enclose the entire [0, 1] range of the brush gradient stops. If the gradient origin is outside the bounds of the ellipse, the brush still works, but its gradient is not well-defined.
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps just one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush ellipse and gradient origin are also transformed.
It is possible to specify an ellipse that does not completely fill area being painted. When this occurs, the
To create a radial gradient brush, use the
A radial gradient brush is a device-dependent resource: your application should create radial gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
-Specifies the center of the gradient ellipse in the brush's coordinate space.
-The center of the gradient ellipse, in the brush's coordinate space.
Specifies the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse.
Specifies the x-radius of the gradient ellipse, in the brush's coordinate space.
-The x-radius of the gradient ellipse. This value is in the brush's coordinate space.
Specifies the y-radius of the gradient ellipse, in the brush's coordinate space.
-The y-radius of the gradient ellipse. This value is in the brush's coordinate space.
Retrieves the center of the gradient ellipse.
-The center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the offset of the gradient origin relative to the gradient ellipse's center.
-The offset of the gradient origin from the center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the x-radius of the gradient ellipse.
-The x-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the y-radius of the gradient ellipse.
-The y-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the
Retrieves or sets the center of the gradient ellipse.
-Retrieves or sets the offset of the gradient origin relative to the gradient ellipse's center.
-Retrieves or sets the x-radius of the gradient ellipse.
-Retrieves or sets the y-radius of the gradient ellipse.
-Retrieves the
Describes a two-dimensional rectangle.
-To create a rectangle geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Contains a reference to a rectangle that describes the rectangle geometry's dimensions when this method returns. You must allocate storage for this parameter.
Retrieves the rectangle that describes the rectangle geometry's dimensions.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-A reference that receives a rounded rectangle that describes this rounded rectangle geometry. You must allocate storage for this parameter.
Retrieves a rounded rectangle that describes this rounded rectangle geometry.
-Paints an area with a solid color.
-To create a solid color brush, use the
A solid color brush is a device-dependent resource. (For more information about resources, see Resources Overview.)
-Specifies the color of this solid-color brush.
-The color of this solid-color brush.
To help create colors, Direct2D provides the ColorF class. It offers several helper methods for creating colors and provides a set or predefined colors.
-Retrieves the color of the solid color brush.
-The color of this solid color brush.
Retrieves or sets the color of the solid color brush.
-Populates an
Populates an
Copies the specified triangles to the sink.
-An array of
The number of triangles to copy from the triangles array.
Closes the sink and returns its error status.
-If this method succeeds, it returns
Represents a geometry that has been transformed.
-Using an
To create an
Direct2D geometries are immutable and device-independent resources created by
Retrieves the source geometry of this transformed geometry object.
-When this method returns, contains a reference to a reference to the source geometry for this transformed geometry object. This parameter is passed uninitialized.
Retrieves the matrix used to transform the
Retrieves the source geometry of this transformed geometry object.
-Retrieves the matrix used to transform the
Renders drawing instructions to a window.
-As is the case with other render targets, you must call BeginDraw before issuing drawing commands. After you've finished drawing, call EndDraw to indicate that drawing is finished and to release access to the buffer backing the render target. For
A hardware render target's back-buffer is the size specified by GetPixelSize. If EndDraw presents the buffer, this bitmap is stretched to cover the surface where it is presented: the entire client area of the window. This stretch is performed using bilinear filtering if the render target is rendering in hardware and using nearest-neighbor filtering if the rendering target is using software. (Typically, an application will call Resize to ensure the pixel size of the render target and the pixel size of the destination match, and no scaling is necessary, though this is not a requirement.)
In the case where a window straddles adapters, Direct2D ensures that the portion of the off-screen render target is copied from the adapter where rendering is occurring to the adapter that needs to display the contents. If the adapter a render target is on has been removed or the driver upgraded while the application is running, this is returned as an error in the EndDraw call. In this case, the application should create a new render target and resources as necessary. -
CreatingTo create an
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Indicates whether the
A value that indicates whether the
Note??If the window was occluded the last time that EndDraw was called, the next time that the render target calls CheckWindowState, it will return
After this method is called, the contents of the render target's back-buffer are not defined, even if the
Returns the
The
Returns the
Describes an elliptical arc between two points.
-The end point of the arc.
The x-radius and y-radius of the arc.
A value that specifies how many degrees in the clockwise direction the ellipse is rotated relative to the current coordinate system.
A value that specifies whether the arc sweep is clockwise or counterclockwise.
A value that specifies whether the given arc is larger than 180 degrees.
Represents a cubic bezier segment drawn between two points.
-A cubic Bezier curve is defined by four points: a start point, an end point (point3), and two control points (point1 and point2). A Bezier segment does not contain a property for the starting point of the curve; it defines only the end point. The beginning point of the curve is the current point of the path to which the Bezier curve is added.
The two control points of a cubic Bezier curve behave like magnets, attracting portions of what would otherwise be a straight line toward themselves and producing a curve. The first control point, point1, affects the beginning portion of the curve; the second control point, point2, affects the ending portion of the curve.
Note??The curve doesn't necessarily pass through either of the control points; each control point moves its portion of the line toward itself, but not through itself.
-The first control point for the Bezier segment.
The second control point for the Bezier segment.
The end point for the Bezier segment.
Describes the extend modes and the interpolation mode of an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes the extend modes and the interpolation mode of an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines a blend description to be used in a particular blend transform.
-Specifies the first RGB data source and includes an optional preblend operation.
Specifies the second RGB data source and includes an optional preblend operation.
Specifies how to combine the RGB data sources.
Specifies the first alpha data source and includes an optional preblend operation. Blend options that end in _COLOR are not allowed.
Specifies the second alpha data source and includes an optional preblend operation. Blend options that end in _COLOR are not allowed.
Specifies how to combine the alpha data sources.
Parameters to the blend operations. The blend must use
Describes the opacity and transformation of a brush.
-This structure is used when creating a brush. For convenience, Direct2D provides the D2D1::BrushProperties function for creating
After creating a brush, you can change its opacity or transform by calling the SetOpacity or SetTransform methods.
-A value between 0.0f and 1.0f, inclusive, that specifies the degree of opacity of the brush.
The transformation that is applied to the brush.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes root-level creation details.
-The threading mode with which the corresponding root objects will be created.
The debug level that the root objects should be created with.
The device context options that the root objects should be created with.
Describes the drawing state of a render target.
-The antialiasing mode for subsequent nontext drawing operations.
The antialiasing mode for subsequent text and glyph drawing operations.
A label for subsequent drawing operations.
A label for subsequent drawing operations.
The transformation to apply to subsequent drawing operations.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes the drawing state of a render target.
-The antialiasing mode for subsequent nontext drawing operations.
The antialiasing mode for subsequent text and glyph drawing operations.
A label for subsequent drawing operations.
A label for subsequent drawing operations.
The transformation to apply to subsequent drawing operations.
The blend mode for the device context to apply to subsequent drawing operations.
Contains the debugging level of an
To enable debugging, you must install the Direct2D Debug Layer.
-Applies to: desktop apps only
Represents a rectangle defined by the upper-left corner pair of coordinates (left,top) and the lower-right corner pair of coordinates (right, bottom). These coordinates are expressed as a 32-bit integer values.
-The x-coordinate of the upper-left corner of the rectangle.
Applies to: desktop apps only
Represents a rectangle defined by the upper-left corner pair of coordinates (left,top) and the lower-right corner pair of coordinates (right, bottom). These coordinates are expressed as a 32-bit integer values.
-The x-coordinate of the upper-left corner of the rectangle.
Contains the position and color of a gradient stop.
-Gradient stops can be specified in any order if they are at different positions. Two stops may share a position. In this case, the first stop specified is treated as the "low" stop (nearer 0.0f) and subsequent stops are treated as "higher" (nearer 1.0f). This behavior is useful if a caller wants an instant transition in the middle of a stop.
Typically, there are at least two points in a collection, although creation with only one stop is permitted. For example, one point is at position 0.0f, another point is at position 1.0f, and additional points are distributed in the [0, 1] range. Where the gradient progression is beyond the range of [0, 1], the stops are stored, but may affect the gradient.
When drawn, the [0, 1] range of positions is mapped to the brush, in a brush-dependent way. For details, see
Gradient stops with a position outside the [0, 1] range cannot be seen explicitly, but they can still affect the colors produced in the [0, 1] range. For example, a two-stop gradient 0.0f, Black}, {2.0f, White is indistinguishable visually from 0.0f, Black}, {1.0f, Mid-level gray. Also, the colors are clamped before interpolation.
-A value that indicates the relative position of the gradient stop in the brush. This value must be in the [0.0f, 1.0f] range if the gradient stop is to be seen explicitly.
The color of the gradient stop.
Contains the
Use this structure when you call the CreateHwndRenderTarget method to create a new
For convenience, Direct2D provides the D2D1::HwndRenderTargetProperties function for creating new
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes image brush features.
-The source rectangle in the image space from which the image will be tiled or interpolated.
The extend mode in the image x-axis.
The extend mode in the image y-axis.
The interpolation mode to use when scaling the image brush.
Contains the starting point and endpoint of the gradient axis for an
Use this method when creating new
The following illustration shows how a linear gradient changes as you change its start and end points. For the first gradient, the start point is set to (0,0) and the end point to (150, 50); this creates a diagonal gradient that starts at the upper-left corner and extends to the lower-right corner of the area being painted. When you set the start point to (0, 25) and the end point to (150, 25), a horizontal gradient is created. Similarly, setting the start point to (75, 0) and the end point to (75, 50) creates a vertical gradient. Setting the start point to (0, 50) and the end point to (150, 0) creates a diagonal gradient that starts at the lower-left corner and extends to the upper-right corner of the area being painted.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes features of a rectangle that is mapped to memory.
-The mapped rectangle is used to map a rectangle into the caller's address space.
-The size in bytes of an individual scanline in the bitmap.
The data inside the bitmap.
Contains the data format and alpha mode for a bitmap or render target.
-For more information about the pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
-A value that specifies the size and arrangement of channels in each pixel.
A value that specifies whether the alpha channel is using pre-multiplied alpha, straight alpha, whether it should be ignored and considered opaque, or whether it is unkown.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Describes a point on a path geometry.
-The end point after walking the path.
A unit vector indicating the tangent point.
The index of the segment on which point resides. This index is global to the entire path, not just to a particular figure.
The index of the figure on which point resides.
The length of the section of the path stretching from the start of the path to the start of endSegment.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
The creation properties for a
Contains the control point and end point for a quadratic Bezier segment.
-The control point of the quadratic Bezier segment.
The end point of the quadratic Bezier segment.
Contains the gradient origin offset and the size and position of the gradient ellipse for an
Different values for center, gradientOriginOffset, radiusX and/or radiusY produce different gradients. The following illustration shows several radial gradients that have different gradient origin offsets, creating the appearance of the light illuminating the circles from different angles.
For convenience, Direct2D provides the D2D1::RadialGradientBrushProperties function for creating new D2D1_RADIAL_GRADIENT_BRUSH structures.
-[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes limitations to be applied to an imaging effect renderer.
-The renderer can allocate tiles larger than the minimum tile allocation. The allocated tiles will be powers of two of the minimum size on each axis, except that the size on each axis will not exceed the guaranteed maximum texture size for the device feature level.
The minimumPixelRenderExtent is the size of the square tile below which the renderer will expand the tile allocation rather than attempting to subdivide the rendering tile any further. When this threshold is reached, the allocation tile size is expanded. This might occur repeatedly until rendering can either proceed or it is determined that the graph cannot be rendered.
The buffer precision is used for intermediate buffers if it is otherwise unspecified by the effects or the internal effect topology. The application can also use the Output.BufferPrecision method to specify the output precision for a particular effect. This takes precedence over the context precision. In addition, the effect might set a different precision internally if required. If the buffer type on the context is
The buffer precision used by default if the buffer precision is not otherwise specified by the effect or the transform.
The tile allocation size to be used by the imaging effect renderer.
Contains rendering options (hardware or software), pixel format, DPI information, remoting options, and Direct3D support requirements for a render target.
-Use this structure when creating a render target, or use it with the
As a convenience, Direct2D provides the D2D1::RenderTargetProperties helper function for creating
Not all render targets support hardware rendering. For a list, see the Render Targets Overview.
Using Default DPI SettingsTo use the default DPI, set dpiX and dpiY to 0. The default DPI varies depending on the render target:
To use the default DPI setting, both dpiX and dpiY must be set to 0. Setting only one value to 0 causes an E_INVALIDARG error when attempting to create a render target.
-A value that specifies whether the render target should force hardware or software rendering. A value of
The pixel format and alpha mode of the render target. You can use the D2D1::PixelFormat function to create a pixel format that specifies that Direct2D should select the pixel format and alpha mode for you. For a list of pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
The horizontal DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
The vertical DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
A value that specifies how the render target is remoted and whether it should be GDI-compatible. Set to
A value that specifies the minimum Direct3D feature level required for hardware rendering. If the specified minimum level is not available, the render target uses software rendering if the type member is set to
Contains the dimensions and corner radii of a rounded rectangle.
-Each corner of the rectangle specified by the rect is replaced with a quarter ellipse, with a radius in each direction specified by radiusX and radiusY.
If the radiusX is greater than or equal to half the width of the rectangle, and the radiusY is greater than or equal to one-half the height, the rounded rectangle is an ellipse with the same width and height of the rect.
Even when both radiuX and radiusY are zero, the rounded rectangle is different from a rectangle., When stroked, the corners of the rounded rectangle are roundly joined, not mitered (square).
-The coordinates of the rectangle.
The x-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
The y-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
Describes the stroke that outlines a shape.
-The following illustration shows different dashOffset values for the same custom dash style.
-The cap applied to the start of all the open figures in a stroked geometry.
The cap applied to the end of all the open figures in a stroked geometry.
The shape at either end of each dash segment.
A value that describes how segments are joined. This value is ignored for a vertex if the segment flags specify that the segment should have a smooth join.
The limit of the thickness of the join on a mitered corner. This value is always treated as though it is greater than or equal to 1.0f.
A value that specifies whether the stroke has a dash pattern and, if so, the dash style.
A value that specifies an offset in the dash sequence. A positive dash offset value shifts the dash pattern, in units of stroke width, toward the start of the stroked geometry. A negative dash offset value shifts the dash pattern, in units of stroke width, toward the end of the stroked geometry.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Describes the stroke that outlines a shape.
-The cap to use at the start of each open figure.
The cap to use at the end of each open figure.
The cap to use at the start and end of each dash.
The line join to use.
The limit beyond which miters are either clamped or converted to bevels.
The type of dash to use.
The location of the first dash, relative to the start of the figure.
The rule that determines what render target properties affect the nib of the stroke.
Contains the three vertices that describe a triangle.
-The first vertex of a triangle.
The second vertex of a triangle.
The third vertex of a triangle.